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

[Karl Berry]

Bruno, Paul, and all,

Alexandre and I have been working on a diff to propose to rms for adding
support for html/pdf/etc. doc in the coding standards.  Before I send it
to him, I thought it would be good to pass it by you.  Bruno, I know you
previously discussed it with rms, but it seems no change ever actually
got installed.

karl


--- /u/karl/gnu/gnuorg/make-stds.texi   2002-09-19 20:40:20.000000000 -0700
+++ /u/karl/gnu/gnuorg/ms.texi  2004-10-09 14:29:56.000000000 -0700
@@ -472,9 +472,29 @@
 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
address@hidden xmldir
+Directories for installing documentation files in the particular
+format.  They should all be set to @code{$(docdir)} by default.
+(If you are using Autoconf, write them as @samp{@@htmldir@@},
address@hidden@@dvidir@@}, etc.)
 
 @item libdir
@@ -655,4 +675,20 @@
 Categories}.
 
address@hidden install-html
address@hidden install-dvi
address@hidden install-pdf
address@hidden install-ps
address@hidden install-xml
+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.
+
+If your package has multiple manuals, or you wish to install HTML
+documentation with many files (such as the ``split'' mode output by
address@hidden --html}, 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}.
+
 @item uninstall
 Delete all the installed files---the copies that the @samp{install}
@@ -768,6 +804,10 @@
 
 @item dvi
-Generate DVI files for all Texinfo documentation.
-For example:
address@hidden html
address@hidden pdf
address@hidden ps
address@hidden xml
+Generate documentation files in the given format, if possible.
+Here's an example rule for generating DVI files from Texinfo:
 
 @smallexample
@@ -785,4 +825,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

Diff finished at Sat Oct  9 14:29:58