Doc Template (Was: Doc-team members going to UDS?)

[Shaun McCance]

On Mon, 2009-10-19 at 11:00 -0400, Kyle Nitzsche wrote:
> Shaun McCance wrote:
> > It's all in gnome-doc-utils.
> >
> > And, by the way, if your goal is to produce HTML that is similar
> > to what users will see in their help viewer, then you should look
> > at using the DocBook stylesheets from gnome-doc-utils as well.
> >
> >   
> 
> Shaun, does gnome-doc-utils apply to downstream (non-gnome) projects? Or 
> is it only suitable for gnome docs?
> 
> I ask because this web page 
> (http://live.gnome.org/GnomeDocUtilsMigrationHowTo) says that 
> translation status is tracked on http://l10n.gnome.org. However, I am 
> targeting generic packages that are not in gnome as well as integration 
> with Launchpad. Naturally, gnome packages should be documented in the 
> gnome project!

gnome-doc-utils provides a few things.  What I was referring
to was using the DocBook->HTML XSLT, which is in no way tied
to Gnome.  There are also common documentation build utilities,
which assume you're using a build system like what we use in
Gnome.  But that pretty much just means autotools.  (We do
have a small amount of glue in gnome-autogen, but it's just
for convenience for us.)

There is nothing in there that ties your documentation to any
of our status tracking systems.  The translation status pages
are generated by a program that has a list of documents to
check.

> My goal is to make it easy (using a standard approach) to add 
> documentation using a well-known and very capable source format to a 
> package or Launchpad project in a way that facilitates integration with 
> Launchpad and that is maximally flexibly regarding support for numerous 
> standard output formats.

Right, understood.  I'm just saying we've built a lot of tools
in Gnome, and we try hard to make them generally useful outside
of core Gnome packages.  Obviously there are going to be bits
in your system that are specific to your setup, but if we can
collaborate on the pieces we can, everybody wins.

And as for the DocBook stylesheets, you have two choices that
I know of: gnome-doc-utils or the well-known standard stylesheets
from Norm & Co.  There are reasons for and against each of them.
gnome-doc-utils doesn't even try to be as complete or as extensible
as docbook-xsl.  But if the documents are ultimately going to be
read in Yelp, then users will see them through gnome-doc-utils.

> My goal is not to subvert ubuntu docs or gnome docs: long may they 
> prosper! :)
> 
> (Just noting that I have had some problems (mentioned previously on this 
> list) customizing ubuntu-docs because the font page (xml & xslt) is hard 
> coded in the yelp package (in Ubuntu anyway) and its format is obscure 
> (very lengthy, desktop style translations in a single file, with xslt 
> providing some content (some links), etc.). As mentioned, I hope yelp 
> soon adds a gconf key (or some other method) that enables yelp to point 
> to a different default front page (without having to patch yelp).)

This whole system is changing with the move to Mallard.  The
front page of Yelp will just be the Desktop Help ("User Guide",
though I'm trying to get away from that term).  Distros will be
able to customize it in all the wondrous ways they can customize
any other Mallard document.

> The Launchpad community is wider than Ubuntu and its big upstreams. 
> Other LP projects may appreciate an easy way to get going with 
> documentation (that is, not having to figure it out from scratch, but 
> just using an existing framework).

That makes sense.  The unfortunate reality right now is that
you need to do different things depending on which desktop
environment you're targeting.  All the effort of writing is
going to be wasted if your document can't be picked up by
the help viewer.

This is something I'd really like to work with the KDE and
XFCE folks to solve.  But currently, if you want to make a
system that's really useful to all the projects in Launchpad,
you're going to need to learn what the different desktops do
and how you can integrate with them.

> Mallard sounds great but has not been deployed yet. I look forward to 
> its smashing success! :)

Well, actually, we did ship a Mallard document in Gnome 2.28,
so it has been deployed.  2.30 will see a bigger rollout.

> Oh, and even if it turns out that doctemplate doesn't use 
> gnome-doc-utils directly, it may makes sense to adopt its source layout. 
> This would simplify the toolchain for integration (import/export) with 
> LP (should that great day ever come ;-)

--
Shaun