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

[Vincent Belaïche]

Answers below...

Le 13/05/2016 à 19:22, Gavin Smith a écrit :
> On 13 May 2016 at 11:14, Vincent Belaïche <vincent.belaiche at domain.hid> wrote:
>
>> 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
>> '@*').
>
> I assume when you say "second occurrence presented as such" you mean
> the boldface used to highlight the name of the environment?
>

Yes this is what I meant.

> This is a misuse of the @deffn-type commands. They're not supposed to
> be used across multiple lines, AFAIK. How about just using the \begin
> line if you want to use one of the @deffn commands?

Then you cannot document how the body of the environment is used.

>
>> we don't use the @deffn and suchlikes commands for describing
>> commands & environment
>
> Why do you want to do this? So that you can automatically extract
> information about the commands and their parameters from the Texinfo
> file?

Not really from the Texinfo file itself, because it may contain macros,
compilation flags (@ifset... @end ifset) and so on, but from some
flatten fully expanded view thereof, like the XML export.

> Macros seem like one possibility for this, allowing processing
> by other programs that could recognize what they mean.
>

Well, IMHO that may obfuscate the manual Texinfo source. Also any tool
made for grabing this information would be done one-shot for that only
manual using the special macros, it would not be able to reuse that tool
for other manuals.

> I found the whole discussion at
> https://mail.gna.org/public/latexrefman-discuss/2016-05/msg00004.html. IMHO
> it's a waste of time trying to persuade someone to use Texinfo.

I don't think that it is a waste of time. The point is all the opposite:
not losing time doing twice the same job with different tools in
different projects while we could work together and find some mutual
interest in our respective objectives.

> If they like it fine, otherwise people gonna use what they gonna
> use. De gustibus non disputandum est.

In the world of libre software, everybody uses the technology that they
prefer. But no-one can achieve any great goal when they work on their
own without any collaboration. That is the whole point.

>
> On the other hand, if there is something that you'd like to express in
> Texinfo source that you can't, fire away with your suggestions!

@deffn is not flexible enough, it covers the needs only for C-like
languages. It would be impossible to use it for languages like Pascal or
Visual Basic that follow a different syntax while they are close in
paradigm (procedural languages). Let alone for TeX dialects that do not
use the same paradigm (macro languages).

It would be great if one could tag elements of the functions as being

- type identifier
- variable identifier
- function identifier
- syntactical element (comma, colon, language keywords, etc.)

For instance some reserved macroes @fnvar{...} etc. could be used for
this tagging.

I can give a hand on the TeX part, but first let us discuss whether or
not such enhancement is desirable.

   Vincent.