Re: [Bug-gnulib] html/doc target in coding standards

[Karl Berry]

    I therefore object to 'xmldir' and --xmldir, 

Fine, whatever, I removed all the xml stuff from the draft.  The
homegrown XML output by makeinfo --xml isn't likely to be of wide use, I
agree.

Perhaps we should have docbook support, though.  I don't know why
docbook doesn't like ‘, but anyway, that's presumably a bug in
makeinfo that's easy to fix.  Whether docbook files produced by other
processors are immediately viewable in browsers, I don't know, but I
know docbook is very widely used.  More widely than Texinfo, in some
circles.

Anyway, I'm not going to insist or persist, so if you object for
whatever reason, that's fine, we'll just leave it out.

    Then the text should say

      If your package has multiple manuals, _AND_ you wish to install HTML
      documentation with many files ...

    with "and", not "or", right? Because when the package has multiple
    manuals, each being in a single file, there is no clutter. And when
    the package has a single manual, and it is installed "split", there
    is no problem either.

This argument makes me realize that the general idea was to say "if your
package has a lot of doc files (for whatever you consider to be 'a
lot'), use subdirs where needed".  I don't think we could or should
legislate this.  So I suppose it would be better to state that general
rule.  See revised text below, which uses the "and" case as an example.

As far as the specifics go, suppose a package had a single large manual.
Many manuals have dozens or even hundreds of nodes.  In that case, 100
tiny .html files and one pdf/dvi/ps would be pretty painful, IMHO.

In the multiple manual scenario, the Emacs distribution has over 20
manuals.  20 manuals times (say) 4 files is 80 files.  That is a lot, in
my estimation, though it's just a matter of taste -- might be nothing at
all to you.

The point is to leave it up to the maintainer.  See revised draft below.

Thanks,
k


--- make-stds.texi      2002-09-19 20:41:39.000000000 -0700
+++ ms.texi     2004-10-17 17:43:53.000000000 -0700
@@ -472,9 +472,32 @@
 string in the file---part of a comment---and @code{grep} for that string.
 
address@hidden docdir
+The directory for installing documentation files (other than Info) for
+this package.  By default, it should be
address@hidden/usr/local/share/doc/@var{yourpkg}}, but it should be written as
address@hidden(datarootdir)/doc/@var{yourpkg}}.  (If you are using Autoconf,
+write it as @samp{@@docdir@@}.)  The @var{yourpkg} subdirectory, which
+may include a version number, prevents collisions among files with
+common names, such as @file{README}.
+
 @item infodir
 The directory for installing the Info files for this package.  By
 default, it should be @file{/usr/local/share/info}, but it should be
 written as @file{$(datarootdir)/info}.  (If you are using Autoconf,
-write it as @samp{@@infodir@@}.)
+write it as @samp{@@infodir@@}.)  @code{infodir} is separate from
address@hidden for compatibility with existing practice.
+
address@hidden htmldir
address@hidden dvidir
address@hidden pdfdir
address@hidden psdir
+Directories for installing documentation files in the particular
+format.  (It is not required to support documentation in all these
+formats.)  They should all be set to @code{$(docdir)} by default.  (If
+you are using Autoconf, write them as @samp{@@htmldir@@},
address@hidden@@dvidir@@}, etc.)  Packages which supply several translations
+of their documentation should install them in
address@hidden(htmldir)/address@hidden, @samp{$(pdfdir)/address@hidden, etc. 
where
address@hidden is a locale abbreviation such as @samp{en} or @samp{pt_BR}.
 
 @item libdir
@@ -655,4 +678,22 @@
 Categories}.
 
address@hidden install-html
address@hidden install-dvi
address@hidden install-pdf
address@hidden install-ps
+These targets install documentation in formats other than Info;
+they're intended to be called explicitly by the person installing the
+package, if that format is desired.  GNU prefers Info files, so these
+must be installed by the @code{install} target.
+
+When you have many documentation files to install, we recommend that
+you avoid collisions and clutter by arranging for these targets to
+install in subdirectories of the appropriate installation directory,
+such as @code{htmldir}.  As one example, if your package has multiple
+manuals, and you wish to install HTML documentation with many files
+(such as the ``split'' mode output by @code{makeinfo --html}), you'll
+certainly want to use subdirectories, or two nodes with the same name
+in different manuals will overwrite each other.
+
 @item uninstall
 Delete all the installed files---the copies that the @samp{install}
@@ -768,6 +809,9 @@
 
 @item dvi
-Generate DVI files for all Texinfo documentation.
-For example:
address@hidden html
address@hidden pdf
address@hidden ps
+Generate documentation files in the given format, if possible.
+Here's an example rule for generating DVI files from Texinfo:
 
 @smallexample
@@ -785,4 +829,18 @@
 write just the dependencies, and allow GNU @code{make} to provide the command.
 
+Here's another example, this one for generating HTML from Texinfo:
+
address@hidden
+html: foo.html
+
+foo.html: foo.texi chap1.texi chap2.texi
+        $(TEXI2HTML) $(srcdir)/foo.texi
address@hidden smallexample
+
address@hidden
+Again, you would define the variable @code{TEXI2HTML} in the Makefile;
+for example, it might run @code{makeinfo --no-split --html}
+(@command{makeinfo} is part of the Texinfo distribution).
+
 @item dist
 Create a distribution tar file for this program.  The tar file should be