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

[Shaun McCance]

On Mon, 2009-10-19 at 12:08 -0400, Kyle Nitzsche wrote:
> Shaun McCance wrote:
> > 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.
> >
> >   
> Currently, doctemplate works:
>  * single source docbook article/book
>  * localized images
>  * i18n/l10n via xml2po and LP
>  * build to pdf, html+css+javascript, localized docbook (via nwalsh + 
> custom xslt)
> 
> I recognize the potential utility of migrating the layout to  that of 
> gnome-doc-utils to facilitate integration with LP (someday).
> 
> However, what other goodies does gnome-doc-utils provide? I'd really 
> like to understand this more fully, but I can't easily find the list of 
> capabilities or documentation. Have any pointers to good info?

I wrote the XSLT in gnome-doc-utils for two primary reasons:
better internationalization and speed.  Last I checked (and
this was a while ago), the internationalization system in
the standard stylesheets had a number of shortcomings that
made things very difficult for our translators.  (Doing i18n
on document formatting turns out to be incredibly hard and
incredibly interesting.)

My benchmarks also showed our stylesheets shaving up to 90%
of the processing time off.  For run-time transformations
like we do in Yelp, every millisecond matters.  The speed
improvements sometimes come at the cost of features.

We've also done a lot of work making sure RTL languages are
rendered correctly, and accessibility issues are important
to us.  I also happen to think the output is prettier out
of the box.

> >> 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.
> >   
> yelp displays html, so that is not strictly the case.

If it has to, sure.  I think it would be a shame if projects
hosted on Launchpad couldn't integrate properly with the help
systems of their target desktops.

> >   
> >> 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.
> >
> >   
> Regarding home page customization for distros, I would really  hope for:
>  * Don't have to modify yelp package to customize front page
>  * Can easily add new topics (to the front page and elsewhere)
>  * Can easily remove topics (from the front page and elsewhere)
> 
> If the list of topics on the front page is static or awkward to modify, 
> then it may not be flexible enough for the wide range of distro 
> modifications that will surely ensue. Or to put it the other way: 
> maximizing customizability is equivalent to maximizing the chances of 
> usage and adoption.

I don't believe in design by committee.  What we need is
people actually hammering on this stuff so we can find and
fix any shortcomings.  There are Ubuntu documentation people
who are actively working on Mallard, and I have to trust
that they're giving me an accurate picture of what Ubuntu
needs from us.

--
Shaun