[texdoc] Some small bugs and more

[Pathe Lists]

Yes, newbies do use the terminal. Newbies try everything, that is how you recognize them.
And they try unexpected things—this is why softwares have to be tested many times.

I have been testing the first commands I found in the table of contents of "LaTeX2e: An unofficial reference manual".

texdoc onecolumn	Sorry, no documentation found for onecolumn.
texdoc twocolumn	Sorry, no documentation found for twocolumn.
texdoc flushbottom	Sorry, no documentation found for flushbottom.
texdoc raggedbottom	Sorry, no documentation found for raggedbottom.
texdoc label		Opens /usr/share/doc/texlive-doc/latex/tex-label/tex-label-doc.pdf
texdoc pageref		Sorry, no documentation found for pageref.
texdoc ref		A web browser opens /usr/share/doc/texlive-doc/etex/base/etex_ref.html
texdoc abstract		Opens /usr/share/doc/texlive-doc/latex/abstract/abstract.pdf
texdoc array		Opens /usr/share/doc/texlive-doc/latex/tools/array.pdf
texdoc center		Opens /usr/share/doc/texlive-doc/latex/moderncv/examples/template_banking_red-fullrules-center.pdf
texdoc centering	Sorry, no documentation found for centering.
texdoc description	Opens /usr/share/doc/texlive-doc/generic/shade/description.pdf
texdoc displaymath	Sorry, no documentation found for displaymath.
texdoc document		Opens /usr/share/doc/texlive-doc/latex/quotchap/document.pdf
texdoc enumerate	Opens /usr/share/doc/texlive-doc/latex/tools/enumerate.pdf

As we can see, texdoc's behaviour could be more efficient.

For example, when a user types "texdoc onecolumn", instead of getting the "no documentation found" reply, he should get a helful advice, like "this topic is described in the (unofficial) reference manual. Would you like to open it? y/n"

How disappointed can a newbie get when prompted with etex_ref.html? From a newbie point of view, the way texdoc reacts is, in that case, irrelevant.

And for "texdoc enumerate", texdoc should reply in interactive mode: "are you interested, at a basic level, by the enumerate command, which is described in LaTeX2e unofficial reference manual? Or, at a more advanced level, are you interested by D. Carlisle wonderful "enumerate" package? Please type 'basic' or 'advanced'.

What do you think?

Patrick
member of GUTenberg, the french user group,
and moderator on texnique.fr, the french TeX Q&A.


Sent: Monday, November 13, 2017 at 5:34 PM
From: "Paulo Roberto Massa Cereda" <cereda.paulo at gmail.com>
To: texdoc at tug.org
Subject: Re: [texdoc] Some small bugs and more
A newbie using a terminal? Sounds highly suspicious. :)

Personally, I am not sure if this is a feasible feature because a good
index would require a lot of constant human intervention... I think texdoc
would be better off focusing on plain, simple, documentation lookup (fuzzy
or literal).

My two cents. :)

Cheerio,

Paulo




A 13 de novembro de 2017 1:12:39 PM, "Pathe Lists" <pathe.lists at gmx.com>
escreveu:

> Yes, I mean "LaTeX2e: An unofficial reference manual".
>  
> And yes, I propose this *only* for this manual.
>  
> Because a newbie will think "hey, I need info about the 'include' command"
> and "hey, I know the texdoc command", so he will type "texdoc include"...
> and (I have just tried it) he will get the 'tikz include' manual, which
> does not meet his need.
>  
> An experienced user wouldn't do that: this is why I propose this *only* for
> the basic commands which appear in the table of contents of "LaTeX2e: An
> unofficial reference manual".
>
> Patrick
> member of GUTenberg, the french user group,
> and moderator on texnique.fr, the french TeX Q&A.
>
>
>
> Sent: Monday, November 13, 2017 at 9:44 AM
> From: "Norbert Preining" <norbert at preining.info>
> To: texdoc at tug.org
> Subject: Re: [texdoc] Some small bugs and more
>> If texdoc starts interacting with the user, couldn't we help a newbie,
>> who would have been typing "texdoc label", with a reply such as "label
>> is described in the LaTeX2e manual ; please type 'texdoc latex2e' to
>> open it"?
>
> And how would we get a definitive list of "xxx" for each of the many
> documents "yyyyy" (in your case xxx=label, yyyyy=latex2e)?
>
> Should that be parsed from the PDF? From the .sty files? From the .dtx
> files?
>
> The only reasonable way would be that someone sits down and compiles a
> list by hand, but it will be very biased I guess.
>
>> It needs a keyword list (containing every command that appears in the
>> table of contents of the manual), and a feature replying, in case of a
>> match, "$1 is described in the LaTeX2e manual ; please type 'texdoc
>> latex2e' to open it".
>
> So do you propose this *only* for the latex manual? That should be
> doable by manually tweaking the texconf.cnf files by adding some alias
> statements.
>
> Furthermore, I guess you mean
> LaTeX2e: An unofficial reference manual
> right?
>
> Norbert
>
> --
> PREINING Norbert http://www.preining.info
> Accelia Inc. + JAIST + TeX Live + Debian Developer
> GPG: 0x860CDC13 fp: F7D8 A928 26E3 16A1 9FA0 ACF0 6CAC A448 860C DC13
>