[tex-live] texdoc in luatex
Robin Fairbairns
Robin.Fairbairns at cl.cam.ac.uk
Mon Jul 2 14:04:17 CEST 2007
Florent Rougon <f.rougon at free.fr> wrote:
> Joachim Schrod <jschrod at acm.org> wrote:
>
> > Please note: metadata about available documentation is already part of the TeX
> > Catalogue and is maintained by the CTAN team in the upload process.
>
> OK. I'm looking at hyperref's metadata now. I see you already have a
> language attribute for each file. Good.
actually, not, in the catalogue repository:
<documentation details='Package README'
href='ctan:/macros/latex/contrib/hyperref/README'/>
<documentation details='Package README, hyper-crossreferenced'
href='ctan:/macros/latex/contrib/hyperref/README.pdf'/>
<documentation details='Manual, HTML version:'
href='ctan:/macros/latex/contrib/hyperref/doc/manual.html'/>
<documentation details='Manual, PDF version:' language='en'
href='ctan:/macros/latex/contrib/hyperref/doc/manual.pdf'/>
<documentation details='Summary of options:' language='en'
href='ctan:/macros/latex/contrib/hyperref/doc/options.pdf'/>
<documentation details='Paper on tagging and navigation:' language='en'
href='ctan:/macros/latex/contrib/hyperref/doc/paper.pdf'/>
in the ones not marked, we rely on a default attribute.
> Do you have some way to specify that one of the files is an entry point
> for the whole documentation? I think that would be nice.
no.
> Also, maybe it would be desirable to have a "type" attribute that at
> least says when the documentation is in text format, because text files
> don't always end in ".txt" (you can find README as well as README.txt,
> or even README.doc in the old DOS times; some packages also ship
> README.en or things like that). Or do you prefer to assume that:
i spend an inordinate amount of my (otherwise) free time scanning for
these things; if i find a *.doc file that's actually plain text, i
simply rename it -- the author's original wishes are probably irrelevant
in today's world, where "microcruft knows best".
> - documentation in text format has either no extension, or ends in
> ".txt"; in this case, README.en is not acceptable and has to be
> renamed to README.en.txt, which:
> 1. would cause too much work for you, I fear;
> 2. would not work on lesser Operating Systems.
the problem is that unless one forces such things, m* is going to fall
in a little heap on the floor, twitching quietly. a text attribute
would be good (though it would of course also require an encoding
attribute -- there are lots of non-ascii iso-646 national variants, as
well as myriad m$ code pages, in use on the archive, and to first order,
there's no way of working out what these things are, other than simply
guessing.
> - non-text formats always provide a recognizable extension in the file
> name.
>
> ?
>
> Given the objection raised by README.en, I think a "type" attribute
> that is used at least for text files would be desirable. Looking at
>
> <documentation href='ctan:/fonts/micropress/hvmath/hvmath.txt'/>
>
> from hvmath-fonts.xml, it seems you don't already do that.
we don't have such a thing in the catalogue dtd, so it can't be done.
yet.
> Another thing I'm missing is a way to map paths such as:
>
> ctan:/macros/latex/contrib/hyperref/README
>
> to paths in the installed TL distro. But I think Norbert has the answer
> to this question or can put it in the infrastructure scripts.
i thought that's what david kastrup's script does. (since my suggestion
of writing another different target for catalogue html generation
received no support at all, i assumed that was the reason.)
> Last thing: AFAIU, you brave catalogue maintainers are the sole people
> responsible for all these XML files. My proposal to embed the metadata
> in each CTAN package was aimed at reducing your workload in this area,
> because careful package maintainers could then provide ready-to-use
> metadata in their uploads to CTAN. Don't you like that?
>
> Is it because you don't trust their input? In this case, you can always
> use what we call an "override file" in Debian, i.e. a version of the
> metadata that *you* wrote and put at a known place on your servers so
> that it takes precedence over the data provided in the uploaded package.
there is no problem in principle. author-provided metadata is a
medium-term aim; in practice, this is taking somewhat longer than we had
hoped. (jim hefferon is giving a paper at tug 2007 about his work in
the related area of automating uploads still further.)
i would concur with joachim that adding still further metadata to
packages, elsewhere, is a route to chaos. however, there is no doubting
that the catalogue is a slow-moving object: it takes me more than a
month to complete a scan of the catalogue to check on a particular
issue. which is not to say that we don't welcome suggestions; however,
given the work-load involved, we simply don't act on any suggestion
that's not thoroughly thought-through, and completely documented.
(fwiw, i'm currently thinking of a way that the catalogue can be used to
generate the by-topic index, automatically. the basic idea is trivial,
but the details are really rather complicated.)
robin
More information about the tex-live
mailing list