[texdoc] texdoc and man pages

[Manuel Pégourié-Gonnard]

Reinhard Kotucha a écrit :
> maybe it's too long ago so that you forgot it already: This is not new
> code, it's a few months old.

Ok. So probably I already played with it :-)

> discussing such things again, it's quite nice to have a piece of code
> which illustrates my ideas.
> 
But can you please just state those ideas with words? Maybe it's easier
than playing with two pieces of code, looking for differences. I though
my code was pretty close to yours.

> Interesting.  When I uploaded VnTeX to CTAN, Robin asked me to rename
> README to README.txt and upload again because files without any
> extension are a pain for Windows users. 
> 
Yep, that would be a good idea.

> Most READMEs do not qualify for texdoc.  I fear that it's too much
> work (and I fear that you neglect your thesis) but maybe it's better
> to "mv README README.txt" in ctan2tds if, and only if, the README
> contains useful information for end-users.
> 
We could probably start doing it for new packages and updates (reviewing
all old packages would be too much of a pain). I like this idea. Karl, wdyt?

>  > I you want to talk about actual file names and locations, I think
>  > files such as Makefile's have nothing to do in the doc/ tree and we
>  > sould care about it in ctan2tds or such.
> 
> Be very careful when you are going to remove them.

Never wanted to remove them. Just put them in the source tree. But for
some reason, Karl doesn't seem to think that sources should go in the
source tree, and prefers to leave them in the doc tree. To me sources
are no the same as documentation, at least they are a very special kind
of documentation, and it would really be better to distinguish between
compiled doc and sources. Karl, any hope to convince you?

> prefer letter to A4.  Hence it make sense to provide the sources.
> 
Sure it does. It always does. The question was only: where to put them?

(Btw we provide a switch for sources installation in the
installer/tlmgr, but if we put most sources in the doc tree, well...)

> However, if the .tex files are in the source tree, nobody knows that
> they exist at all.

Hum, I don't agree. People know that they kept the checkbox "install
sources" checked, so they expect the source to be somewhere. If they
don't find it in doc, they don't even need to read tds.pdf to guess that
they should be in source.

>  Everything
> not supposed to be found by texdoc could be moved to the source tree
> then.

Al long as it's actual source. Readme's and so on should be kept in the
doc tree. But yes, it's precisely my idea: sources should go in source,
and docs in doc. I mean, okay, most of us here are geeks who learn
things from reading the source when documentation is not enough, but we
still know the difference between actual doc and source, don't we?

> Of course, there is a lot of old stuff we have to take as it is.  But
> isn't it quite strange that the pstricks guys asked you for an alias
> because "texdoc pstricks" didn't work instead of providing a file
> pstricks.pdf?  It seems that Heiko's solution lacks advertising.  
> 
Yep.

> If there are two different files with the same name, the result is
> unpredictable.  That's all I'm concerned about.
> 
See my other answer. This is a task for texdoc, not kpse. (And remember
you can always use the mixed mode of texdoc, it's precisely intended for
this kind of situation. You can even select the mixed mode as default in
your texdoc.cnf.)

> And does it really matter at all whether texdoc derives the
> information (that a particular file is a man page) from the file name
> or from the path?
> 
Not really. But the question is, when someone types in NAME, do wo
really want to search for NAME.1 and NAME.5 too?

Manuel.

PS: life would indeed be easier if we could assume relevant files have
an extension.