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

[Kyle Nitzsche]

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?
>> 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.
>   
>> 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.

>> 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.
>   
Good points. My thinking is that by supporting multiple standard output 
formats (including html+css+javascript), all desktops should have 
facilities for run-time display.  As noted previously, I have led 
development of html help that was displayed in yelp.
>   
>> 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.
>   
I stand corrected. :)

Kyle
>   
>> 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
>
>
>