I'm in the process of packaging Clozure Common Lisp
(ccl.clozure.com). The CCL manual exists in both single file and
multiple file versions. The two version versions are online here under
the Documentation heading. The single page is
http://ccl.clozure.com/ccl-documentation.html and the multiple page
one is http://ccl.clozure.com/manual/. The current version of
ccl.doc-base is given below. As you can see, I would like to have two
HTML sections there. However, it seems this is not currently
possible. The doc-base manual 2.3.2.2: "Format sections" has

"There must be at least one such a section. If there are more, each of
them must register files in different formats (e.g. having two Format:
HTML sections in one control file is not allowed)."

(Minor comment: this should be "at least one such section", not "at
least one such a section").

It seems install-docs does not check for this.

usr/sbin/install-docs -v --check debian/ccl.doc-base
Warning in `debian/ccl.doc-base', line 9: `Files' value not specified for format `html'.
debian/ccl.doc-base: 1 warning or non-fatal error found.

though lintian does.

Now running lintian...

E: ccl: doc-base-file-lacks-required-field ccl-manual:9 files
E: ccl: doc-base-file-duplicated-format ccl-manual:10 html

I can't see any reason why this is not allowed. Regardless, what is
the best thing to do in this situation?  Register one version and not
the other? Suppose that some package contained two completely
different html documents. What would one do then?

Finally, another minor comment. In `man install-docs` there is

SEE ALSO
       dhelp(1), doccentral(1)

but I think it should be 'doc-central'.

##################################################################
ccl.doc-base
##################################################################
Document: ccl-manual
Title: Debian CCL Manual
Author: CCL Developers
Abstract: The CCL manual, describing what how to install and use CCL
Section: Programming/Common Lisp

Format: HTML
Index: /usr/share/doc/ccl/ccl-documentation.html

Format: HTML
Index: /usr/share/doc/ccl/manual/index.html
Files: /usr/share/doc/ccl/manual/*.html
###################################################################

On Sun, 22 Jul 2012 23:50:47 +0530 Faheem Mitha <faheem@faheem.info> wrote:
[...]

See example below.


[...]

One can at least define two doc-base files with two distinct document
IDs, arguably with some duplication.

Say:
 > Index: /usr/share/doc/ccl/ccl-documentation.html

Note than the last Index line in case of a single file documentation
is completely redundant but has to be there,
see https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=706927

Maybe the following syntax should be allowed for single-page HTML
documents, and Index should only be allowed for multiple-page ones,
fixing both problems:

 > Format: HTML
 > Files: /usr/share/doc/ccl/ccl-documentation.html

As the above currently does not work anyway, using that syntax
should not cause problems for unmodified existing files.