Re: [help-texinfo] [latexrefman-discuss] latexrefman / ltxref.org

[Vincent Belaïche]

Feedback below...

Looping also texinfo help.

Le 12/05/2016 12:52, Patrick Gundlach a écrit :
> Hello Vincent,
>
>> Just a few questions to clarify your needs/objectives:
>>
>> - Is your objective to provide a short description (synopsis) for each
>>  command, or do you want to make a reference manual (ie exhaustive and
>>  factual description) ?
>
> well, kind of both. I'd like to have a synopsis for each command /
> package / environment and a concise description as well. The
> description should be long enough to make clear what the command /
> package / .. is about, but not much more. If it takes an example to
> that, than I'd include an example.
>

It seems to me that the latexrefman project is after the same
objective. So the statement made by Karl that:

   The crucial point is that he is coming up with a single sentence to
   describe features, and it would not make sense for us to try to write
   the exact sentence he wants in our manual.  It's a different purpose.

seems not to be what you want to do.

>> - If you don't use Texinfo to make your site, is that just because you
>>  don't know enough Texinfo, otherwise what limitations in Texinfo made
>>  you discard it as the language supporting content production ?
>
> I use XML as an export format and as an input format (round trip). See
> for example
>
> https://ltxref.org/?format=xml
>
> or for a command (not much filled in yet)
>
> https://ltxref.org/cmd/%5Cdocumentclass?format=xml
>
> texinfo is too verbose for me. The idea is to have a fully and easily
> parseable output format to generate more interesting stuff that I am
> not aware of yet. And my day to day work is around XML, so that
> suggests itself to use that. I just need some help / source to fill in
> the gaps.
>
>
>> - What means do you use to develop your site, do you directly write HTML
>>  code plus some javascript and CSS to make it more interactive and look
>>  nicer ?
>
> First I read the XML file into the server and then generate
> (templating system) the HTML files from that.
>
>
> Patrick
>
>

Texinfo can export XML in two ways, either Texinfo own XML, that
represent a machine processable form of the output, and second docbook
XML --- which is a standard format used by some publishers.

Have you investigated whether one of these 2 formats could fulfill your
needs.

The point is that in the latexrefman project we don't use the @deffn and
suchlikes commands for describing commands & environment. So the format
of synopsis is just plain text and it may be difficult for you to grab
the arguments and so on to exploit them with your server program (is
that program done in PHP ?)

I have made a short example attached using @deftypefn, but for
environment I did not find any way to make the second occurrence of the
environment name presented as such (it seems to be some limitation of
Texinfo, no command to recall the function name). Also the indentation
is not so good when you make it multiline (with '@*').

   Vincent.

\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename toto.info
@settitle NAME-OF-MANUAL VERSION
@c %**end of header

@copying
This manual is for PROGRAM, version VERSION.

Copyright @copyright{} YEARS COPYRIGHT-OWNER.

@quotation
Permission is granted to ...
@end quotation
@end copying

@titlepage
@title NAME-OF-MANUAL-WHEN-PRINTED
@subtitle SUBTITLE-IF-ANY
@subtitle SECOND-SUBTITLE
@author AUTHOR

@c  The following two commands
@c  start the copyright page.
@page
@vskip 0pt plus 1filll
@insertcopying

Published by ...
@end titlepage

@c So the toc is printed at the start.
@contents

@ifnottex
@node Top
@top TITLE

This manual is for PROGRAM, version VERSION.
@end ifnottex

@menu
* First Chapter::    Getting started ...
* \section::    The @code{\section} command 
* itemize::    The @code{itemize} environment
* Index:: Index
@end menu

@node First Chapter
@chapter First Chapter

@cindex first chapter
@cindex chapter, first

@node \section
@chapter The @code{\section} command

@deftypefn Command \section @var{*} @code{[} @var{toc-title} @code{]} 
@address@hidden @var{title} @address@hidden
@table @var
@item *
Optional; when present the title is unnumbered.
@item @var{toc-title}
Optional; when present the title as in the table of content.
@item @var{title}
Required; the title.
@end table

@end deftypefn

@node itemize
@chapter The @code{itemize} environment

@deftypefn Environment  @address@hidden itemize @address@hidden@* 
@address@hidden @address@hidden itemize @address@hidden
@table @var
@item @var{body}
Required; the body of it
@end table

@end deftypefn


@node Index
@unnumbered Index

@printindex cp

@bye
        

This is toto.info, produced by texi2any version 6.1dev+dev from
toto.texi.

This manual is for PROGRAM, version VERSION.

   Copyright (C) YEARS COPYRIGHT-OWNER.

     Permission is granted to ...


File: toto.info,  Node: Top,  Next: First Chapter,  Up: (dir)

TITLE
*****

This manual is for PROGRAM, version VERSION.

* Menu:

* First Chapter::    Getting started ...
* \section::    The '\section' command
* itemize::    The 'itemize' environment
* Index:: Index


File: toto.info,  Node: First Chapter,  Next: \section,  Prev: Top,  Up: Top

1 First Chapter
***************


File: toto.info,  Node: \section,  Next: itemize,  Prev: First Chapter,  Up: Top

2 The '\section' command
************************

 -- Command: \section * '[' TOC-TITLE ']' '{' TITLE '}'
     *
          Optional; when present the title is unnumbered.
     TOC-TITLE
          Optional; when present the title as in the table of content.
     TITLE
          Required; the title.


File: toto.info,  Node: itemize,  Next: Index,  Prev: \section,  Up: Top

3 The 'itemize' environment
***************************

 -- Environment: '\begin{' itemize '}'
          BODY
          '\end{' itemize '}'
     BODY
          Required; the body of it


File: toto.info,  Node: Index,  Prev: itemize,  Up: Top

Index
*****

[index]
* Menu:

* chapter, first:                        First Chapter.         (line 5)
* first chapter:                         First Chapter.         (line 6)



Tag Table:
Node: Top198
Node: First Chapter469
Node: \section582
Node: itemize967
Node: Index1230

End Tag Table

NAME-OF-MANUAL VERSION

Table of Contents

• 1 First Chapter
• 2 The \section command
• 3 The itemize environment
• Index

Next: First Chapter, Up: (dir)   [Contents][Index]

TITLE

This manual is for PROGRAM, version VERSION.

• First Chapter:		Getting started ...
• \section:		The \section command
• itemize:		The itemize environment
• Index:		Index

---

Next: \section, Previous: Top, Up: Top   [Contents][Index]

1 First Chapter

---

Next: itemize, Previous: First Chapter, Up: Top   [Contents][Index]

2 The \section command

Command: \section * [ toc-title ] { title }

*

Optional; when present the title is unnumbered.

toc-title

Optional; when present the title as in the table of content.

title

Required; the title.

---

Next: Index, Previous: \section, Up: Top   [Contents][Index]

3 The itemize environment

Environment: \begin{ itemize }
body
\end{ itemize }

body

Required; the body of it

---

Previous: itemize, Up: Top   [Contents][Index]

Index

Jump to:	C   F

	Index Entry		Section
C
	chapter, first:		First Chapter
F
	first chapter:		First Chapter

Jump to:	C   F

---

<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"; [
  <!ENTITY tex "TeX">
  <!ENTITY latex "LaTeX">
]>
<book id="toto.xml" lang="en">
<title>NAME-OF-MANUAL VERSION</title>
<!-- %**end of header -->

<bookinfo><legalnotice><para>This manual is for PROGRAM, version VERSION.
</para>
<para>Copyright &#169; YEARS COPYRIGHT-OWNER.
</para>
<blockquote><para>Permission is granted to ...
</para></blockquote></legalnotice></bookinfo>

<!--  The following two commands -->
<!--  start the copyright page. -->
<para>This manual is for PROGRAM, version VERSION.
</para>
<para>Copyright &#169; YEARS COPYRIGHT-OWNER.
</para>
<blockquote><para>Permission is granted to ...
</para></blockquote>

<para>Published by ...
</para>
<!-- So the toc is printed at the start. -->

<chapter label="" id="Top">
<title>TITLE</title>

<para>This manual is for PROGRAM, version VERSION.
</para>

</chapter>
<chapter label="1" id="First-Chapter">
<title>First Chapter</title>

<indexterm role="cp"><primary>first chapter</primary></indexterm>
<indexterm role="cp"><primary>chapter, first</primary></indexterm>

</chapter>
<chapter label="2" id="_005csection">
<title>The <literal>\section</literal> command</title>

<synopsis><indexterm 
role="fn"><primary><replaceable>*</replaceable></primary></indexterm><phrase 
role="category"><emphasis role="bold">Command</emphasis>:</phrase> 
<returnvalue>\section</returnvalue> 
<function><replaceable>*</replaceable></function> <type>[</type> 
<replaceable><replaceable>toc-title</replaceable></replaceable> <type>]</type> 
<replaceable>{</replaceable> 
<replaceable><replaceable>title</replaceable></replaceable> 
<type>}</type></synopsis>
<blockquote><variablelist><varlistentry><term><replaceable>*</replaceable>
</term><listitem><para>Optional; when present the title is unnumbered.
</para></listitem></varlistentry><varlistentry><term><replaceable><replaceable>toc-title</replaceable></replaceable>
</term><listitem><para>Optional; when present the title as in the table of 
content.
</para></listitem></varlistentry><varlistentry><term><replaceable><replaceable>title</replaceable></replaceable>
</term><listitem><para>Required; the title.
</para></listitem></varlistentry></variablelist>
</blockquote>
</chapter>
<chapter label="3" id="itemize">
<title>The <literal>itemize</literal> environment</title>

<synopsis><indexterm role="fn"><primary>itemize</primary></indexterm><phrase 
role="category"><emphasis role="bold">Environment</emphasis>:</phrase>  
<returnvalue>\begin{</returnvalue> <function>itemize</function> 
<type>}</type><replaceable>
</replaceable> 
<replaceable><replaceable>body</replaceable></replaceable><replaceable>
</replaceable> <type>\end{</type> <replaceable>itemize</replaceable> 
<type>}</type></synopsis>
<blockquote><variablelist><varlistentry><term><replaceable><replaceable>body</replaceable></replaceable>
</term><listitem><para>Required; the body of it
</para></listitem></varlistentry></variablelist>
</blockquote>

</chapter>
<chapter label="" id="Index">
<title>Index</title>

<index role="cp"></index>

</chapter>
</book>

<?xml version="1.0"?>
<!DOCTYPE texinfo PUBLIC "-//GNU//DTD TexinfoML V6.0//EN" 
"http://www.gnu.org/software/texinfo/dtd/6.0/texinfo.dtd";>
<texinfo xml:lang="en">
<filename file="toto.xml"></filename>
<preamble>\input texinfo   @c -*-texinfo-*-
</preamble><!-- c %**start of header -->
<setfilename file="toto.info" spaces=" ">toto.info</setfilename>
<settitle spaces=" ">NAME-OF-MANUAL VERSION</settitle>
<!-- c %**end of header -->

<copying endspaces=" ">
<para>This manual is for PROGRAM, version VERSION.
</para>
<para>Copyright &copyright; YEARS COPYRIGHT-OWNER.
</para>
<quotation endspaces=" ">
<para>Permission is granted to ...
</para></quotation>
</copying>

<titlepage endspaces=" ">
<title spaces=" ">NAME-OF-MANUAL-WHEN-PRINTED</title>
<subtitle spaces=" ">SUBTITLE-IF-ANY</subtitle>
<subtitle spaces=" ">SECOND-SUBTITLE</subtitle>
<author spaces=" ">AUTHOR</author>

<!-- c  The following two commands -->
<!-- c  start the copyright page. -->
<page></page>
<vskip> 0pt plus 1filll</vskip>
<insertcopying></insertcopying>

<para>Published by ...
</para></titlepage>

<!-- c So the toc is printed at the start. -->
<contents></contents>

<node name="Top" spaces=" "><nodename>Top</nodename><nodenext 
automatic="on">First Chapter</nodenext><nodeup 
automatic="on">(dir)</nodeup></node>
<top spaces=" "><sectiontitle>TITLE</sectiontitle>

<para>This manual is for PROGRAM, version VERSION.
</para>
<menu endspaces=" ">
<menuentry leadingtext="* "><menunode separator="::    ">First 
Chapter</menunode><menudescription><pre xml:space="preserve">Getting started ...
</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode 
separator="::    ">\section</menunode><menudescription><pre 
xml:space="preserve">The <code>\section</code> command 
</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode 
separator="::    ">itemize</menunode><menudescription><pre 
xml:space="preserve">The <code>itemize</code> environment
</pre></menudescription></menuentry><menuentry leadingtext="* "><menunode 
separator=":: ">Index</menunode><menudescription><pre xml:space="preserve">Index
</pre></menudescription></menuentry></menu>

</top>
<node name="First-Chapter" spaces=" "><nodename>First 
Chapter</nodename><nodenext automatic="on">\section</nodenext><nodeprev 
automatic="on">Top</nodeprev><nodeup automatic="on">Top</nodeup></node>
<chapter spaces=" "><sectiontitle>First Chapter</sectiontitle>

<cindex index="cp" spaces=" "><indexterm index="cp" number="1">first 
chapter</indexterm></cindex>
<cindex index="cp" spaces=" "><indexterm index="cp" number="2">chapter, 
first</indexterm></cindex>

</chapter>
<node name="_005csection" spaces=" "><nodename>\section</nodename><nodenext 
automatic="on">itemize</nodenext><nodeprev automatic="on">First 
Chapter</nodeprev><nodeup automatic="on">Top</nodeup></node>
<chapter spaces=" "><sectiontitle>The <code>\section</code> 
command</sectiontitle>

<deftypefn spaces=" " endspaces=" "><definitionterm><indexterm index="fn" 
number="1"><var>*</var></indexterm><defcategory>Command</defcategory> 
<deftype>\section</deftype> <deffunction><var>*</var></deffunction> 
<defparamtype><code>[</code></defparamtype> 
<defparam><var>toc-title</var></defparam> 
<defparamtype><code>]</code></defparamtype> 
<defparam><code>&lbrace;</code></defparam> 
<defparam><var>title</var></defparam> 
<defparamtype><code>&rbrace;</code></defparamtype></definitionterm>
<definitionitem><table commandarg="var" spaces=" " endspaces=" ">
<tableentry><tableterm><item spaces=" "><itemformat 
command="var">*</itemformat></item>
</tableterm><tableitem><para>Optional; when present the title is unnumbered.
</para></tableitem></tableentry><tableentry><tableterm><item spaces=" 
"><itemformat command="var"><var>toc-title</var></itemformat></item>
</tableterm><tableitem><para>Optional; when present the title as in the table 
of content.
</para></tableitem></tableentry><tableentry><tableterm><item spaces=" 
"><itemformat command="var"><var>title</var></itemformat></item>
</tableterm><tableitem><para>Required; the title.
</para></tableitem></tableentry></table>

</definitionitem></deftypefn>

</chapter>
<node name="itemize" spaces=" "><nodename>itemize</nodename><nodenext 
automatic="on">Index</nodenext><nodeprev 
automatic="on">\section</nodeprev><nodeup automatic="on">Top</nodeup></node>
<chapter spaces=" "><sectiontitle>The <code>itemize</code> 
environment</sectiontitle>

<deftypefn spaces=" " endspaces=" "><definitionterm><indexterm index="fn" 
number="2">itemize</indexterm><defcategory>Environment</defcategory>  
<deftype><code>\begin&lbrace;</code></deftype> 
<deffunction>itemize</deffunction> 
<defparamtype><code>&rbrace;</code></defparamtype><defparam>&linebreak;</defparam>
 <defparam><var>body</var></defparam><defparam>&linebreak;</defparam> 
<defparamtype><code>\end&lbrace;</code></defparamtype> 
<defparam>itemize</defparam> 
<defparamtype><code>&rbrace;</code></defparamtype></definitionterm>
<definitionitem><table commandarg="var" spaces=" " endspaces=" ">
<tableentry><tableterm><item spaces=" "><itemformat 
command="var"><var>body</var></itemformat></item>
</tableterm><tableitem><para>Required; the body of it
</para></tableitem></tableentry></table>

</definitionitem></deftypefn>


</chapter>
<node name="Index" spaces=" "><nodename>Index</nodename><nodeprev 
automatic="on">itemize</nodeprev><nodeup automatic="on">Top</nodeup></node>
<unnumbered spaces=" "><sectiontitle>Index</sectiontitle>

<printindex value="cp" line=" cp"></printindex>

</unnumbered>
<bye></bye>
</texinfo>

toto.pdf
Description: Adobe PDF document