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

[Kyle Nitzsche]

Shaun McCance wrote:
> On Fri, 2009-10-16 at 15:39 -0400, Kyle Nitzsche wrote:
>   
>> Jim Campbell wrote:
>>     
>>> On Fri, Oct 16, 2009 at 12:57 PM, Ian <vern at riseup.net> wrote:
>>>   
>>>       
>>>> Hi
>>>>     
>>>>         
>>>>> I am hoping to hold a session on 'doctemplate.' This is a 'template'
>>>>> I've been developing hosted on LP (https://launchpad.net/doctemplate)
>>>>> that allows one to create new documentation:
>>>>>  * Whose source is docbook (article or book)
>>>>>  * That is easily localizable (images, strings)
>>>>>  * That supports numerous localized outputs: pdf, html (with a
>>>>> javascript-based UI with a navigation TOC, next/previous buttons, etc),
>>>>> docbook
>>>>>  * All controlled by a few simple and well-documented make commands.
>>>>>  * Optional installation with package installation such that it is
>>>>> registered with rarian for display in yelp.
>>>>>  * String localization can be done in LP in a straightforward manner.
>>>>>       
>>>>>           
>>>> Some more ideas:
>>>>
>>>> When you sign up to the doc team through LP, the first thing you’ll do
>>>> is check the  project you want out of bazaar
>>>> You send stuff by checking it in
>>>> The continuous build system will let you see your contributions
>>>> formatted as it will be printed in pdf/html etc.
>>>> And, if your contribution contains code it is kept in separate source
>>>> code files and the build system will include the extracts you want
>>>> directly into the formatted final document (and it’ll syntax highlight
>>>> them along the way).
>>>>
>>>> I will be @ UDS for the meeting
>>>>
>>>>     
>>>>         
>> Looking forward to seeing you there, Ian, and talking more about these 
>> ideas.
>>     
>>>> Ian
>>>>
>>>> --
>>>> http://ianlawrence.info
>>>>
>>>>     
>>>>         
>>> I've started this as a new thread.  I'm hopeful that this project
>>> could be made to work with Mallard syntax (the xml-based syntax that
>>> is being used for new upstream GNOME documentation) 
>>>       
>> If Mallard provides xslt transforms that convert it into html (like 
>> nwalsh's do for docbook) then this is possible. As a first step, I 
>> assume the source is a docbook article or book. Mallard looks very 
>> interesting, but I don't really know enough about it yet.
>>     
>
> 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!

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.

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

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

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

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 ;-)

Cheers,
Kyle


> --
> Shaun
>
>
>