[texdoc] Some small bugs and more

[Reinhard Kotucha]

On 2017-11-13 at 20:16:21 +0100, Pathe Lists wrote:

 > Yes, newbies do use the terminal. Newbies try everything, that is
 > how you recognize them.

Patrick, I'm using the terminal extensively.  Do you now think that
I'm a newbie?  You said that this is how you recognize them. ;)

 > [...]
 > 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.

Well, the purpose of texdoc is to locate the documentation of
packages.  What you suggest is something completely different.  The
argument of texdoc is a package name but you want to allow a macro or
environment name as well.  Not a good idea at all.  Furthermore,
texdoc is not restricted LaTeX but if you follow your approach
consistently, you cannot avoid to confuse LaTeX users with non-LaTeX
stuff.

What you actually want is a new program.  Its name should make clear
that it supports LaTeX only.  Writing such a program is not a big
deal and I'll write it with pleasure if someone provides a database
I can rely on.

The nasty thing is the database which maps macro or environment names
to files.  There is currently nothing we can use and everything has to
be written from ground up.  If you don't intend to support all LaTeX
packages available today, the amount of work is still huge but
limited.  It doesn't make sense to support control sequences in files
like pgfmanual.pdf or beameruserguide.pdf, for example.  However, for
standard LaTeX stuff, like graphics related control sequences, it's
better to refer to LaTeX docs (grfguide.pdf in this case) rather than
to latex2e.pdf.  Similar probably with amsmath.

The database is unavoidable anyway, regardless whether we write a new
program or hijack texdoc.  I definitely vote for a new program because
it's counterproductive to allow package and control sequence names as
argumets at the same time.  This would render texdoc unusable.  And we
don't need texdoc's search facilities if we know in advance in which
file a particular control sequence is described.

Could you estimate the amount of work necessary to create such a
database?  A good starting point is the documentation provided by
LaTeX itself, latex2e.pdf should only be consulted if a particular
item isn't found there.

If you think that you can provide such a database we can discuss the
details later.

 > 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'.

texdoc should always be able to produce machine-readable output.  The
reason is that the search results should also be accessible by GUI
tools.  I doubt that we can pass what you suggest to a GUI easily.
The output of texdoc should always be either a string or a list.

 > What do you think?

IMO such a command reference is quite convenient.  But especially with
newbies in mind, I'm convinced that such a command reference can never
replace a good text book about LaTeX.  The latter is what newbies need
in the first place.

Regards,
  Reinhard

-- 
------------------------------------------------------------------
Reinhard Kotucha                            Phone: +49-511-3373112
Marschnerstr. 25
D-30167 Hannover                    mailto:reinhard.kotucha at web.de
------------------------------------------------------------------