Re: describing config files

[Patrice Dumas]

On Tue, May 23, 2023 at 09:58:47AM +0100, Joao Dinis wrote:
> Hi,
> 
> I'm a newbie on texinfo, using to write an users manual.
> In that process I found the need to detail a configuration file by showing a
> few lines of it, followed by a description of what those lines mean, then
> showing a few more, describing, and so on.
> 
> The full config file will go in an appendix (~500 lines long).  But, it
> would be great if the users could have a line number preceding each line.
> To make that work, the line numbers should be typeset slightly smaller or
> grayed (or even the two), to avoid confusion with the body of the config
> file.
> 
> I found no way to do that with texinfo.  I'm almost sure it can't be done
> straight out from the box.  Does anyone has some idea how to do it?

What output format would you want it for?  In Info, my guess is that it
would be quite confusing.  In HTML, LaTeX and PDF, it would probably
make sense.  I can imagine how to do it in HTML, and in LaTeX it would
depend on existing packages.

> If not possible, and since I think this could be useful in many scenarios,
> it would be great to have something like:

This does not follow the philosophy of Texinfo, to be mostly semantic.

I see two possiblities to do it more semantically
1) for @example only, add semantics to the second argument to set line
   counting. The line count would always start at 1
2) a global @set XXX or specific @-command that turns on lines counting
   for @example/@list/@display/@format... And @verbatim?  The line count
   would always start at 1
3) give an argument to @verbatiminclude (or use a new @-command) to
   include specific lines of an input file and another argument to
   have the line count shown.

Those two possibilities would not really correspond to your need, as it
seems to me that you also want to control the starting line 

> @example
> @color{gray}{11} start = 102
> @end example
> 
> to typeset the 11 in gray (in tt font), a space, and the the start = 102 in
> typewriter as usual.
> 
> Or perhaps even:
> 
> @example
> @datafile{11-21}{config.dat}
> @end example
> 
> To have lines 11 to 21 of config.dat (and only those) inserted there, with
> line numbers in gray, as exemplified above.  Without no line number argument
> it could insert the all file.

@verbatiminclude includes a whole file, but there is no equivalent for
@example.  And no possibility to start at a specific line, nor line
counting.

> Not sure if this is the right place for feature request, but here is it.

It is the right place.

-- 
Pat