[Phpwm] Web application documentation - write once / output multiple formats

[Ian Munday]

On 29 May 2009, at 10:23, David Goodwin wrote:

> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> Ian Munday wrote:
>> Slightly off-topic perhaps, but I'm wondering how people provide /
>> deliver document for their applications?
>>
>> Historically, I've manually created HTML pages that I bring together
>> with a simple table of contents (TOC) and which then load in a pop-up
>> window.  I can link to specific pages from within my application to
>> make it 'context-sensitive'.  A real requirement going forward is to
>> improve the way help documentation is delivered in HTML (i.e. make it
>> searchable), and also to provide multiple formats.  I also want a
>> write-once, but output in multiple formats solution.  (Longer term  
>> I'm
>> also thinking multiple languages - clearly each language will need to
>> be written.)
>>
>> The formats that have been identified as most useful / relevant to  
>> the
>> type of applications I'm involved in are:
>>
>>   *  HTML - searchable and with a tree-like TOC - a good example is http://livedocs.adobe.com/en_US/Lightroom/1.0/help.html?content=WSF3A57C22-0CDF-4401-9C10-2D0B3B7C7E40.html
>>   *  PDF
>>   *  CHM
>>
>> Has anyone found a good solution to this problem?
>>
>> Regards,
>>
>
>
> Aside from just having 3 different 'view' templates for each? No.  
> (Or am
> I missing the question?)
>
> PDF is kind of the hardest, although we did use PDML once (with mixed
> success).
>
> Never touched CHM so can't comment.
>
> David.

CHM is a format I've not touched myself, but it's something that has  
been requested a couple of times.  I think the order I've listed them  
are also my priority.

   (1)  HTML - first and foremost, with a TOC, index and is  
searchable.  This can be run off a product website, or integrated into  
the application.
   (2)  PDF - great for anything offline, and also useful for running  
training.
   (3)  CHM - a nice bonus for those who are fussy.

I'm aware of DocBook ( http://www.docbook.org and http://en.wikipedia.org/wiki/DocBook 
  ) but have never used it and am not sure whether it can produce the  
type of HTML (e.g. http://livedocs.adobe.com/en_US/Lightroom/1.0/help.html?content=WSF3A57C22-0CDF-4401-9C10-2D0B3B7C7E40.html 
  ) I'm interested in.

Regards,

Ian