[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'
  <documentation details='Package README, hyper-crossreferenced'
  <documentation details='Manual, HTML version:'
  <documentation details='Manual, PDF version:'  language='en'
  <documentation details='Summary of options:'  language='en'
  <documentation details='Paper on tagging and navigation:'  language='en'

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.


> 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

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

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


More information about the tex-live mailing list