new docs are not converted to html

[Ian Clatworthy]

Aaron Bentley wrote:

> The user reference should be a thick book.  Bazaar should not be a thick
> book.  As I see it, help topics are supplements to the command help.

Interesting. At the moment, the advantage of fully building the User
Reference from the on-line help is consistency. If we're going to have
parts of the User Reference outside online help, what guideline/rule do
you suggest for deciding whether something goes in or out? If we can
come up with a rule that would make sense to end users, I'm open to
adopting it. (I don't wish to see bug reports on "help doesn't include
topic X yet it's in the User Reference".)

I'm not so convinced (yet) about the "not be a thick book" bit. With the
API reference (epydoc) generated from the shipped code, it's already a
thick book. :-)

Seriously, a few more dozen pages of embedded online help topics won't
make a lot of difference will it? In comparison, if we do end up having
the doc translated into multiple languages and added to the source tree,
that will be 100s of pages per language.

>> There should be no special files in en/user-reference
> 
> Then why is it there?  I was shocked to find it empty.

It's there to be a container for the generated doc to be put into. The
general directory scheme under doc (except for developers/) is:

  language-code/doc-name

user-reference isn't the only empty one under en/. release-notes is a
container for NEWS and developer-guide is a container for HACKING.
For non-English languages, these directories may not be empty btw.

If it helps, I could put a README into those directories explaining why
they are there. I'm also proposing to update HACKING explaining all the
above, assuming you (and other core developers) are OK with it.

> Also, I should note that the Hook reference refers to the user guide,
> which plays into the discussion of "more agressive error check for `make
> docs`" in your other email.

Cool. Thanks for another reference point. I really do think limiting
what docs can cross-reference is doing readers a dis-service.


Ian C.