[Box Backup-dev] [Doc] Format of the documentation

[Per Thomsen]

On 3/1/06 5:17 AM, Ben Summers wrote:
> On 27 Feb 2006, at 18:31, Per Thomsen wrote:
>> On 2/27/06 3:40 AM, Ben Summers wrote:
>>> On 27 Feb 2006, at 06:21, Per Thomsen wrote:
>>>> Documenters,
>>>> I think the first thing we need to decide is what format we should use
>>>> for the documentation, and then get the existing docs (fluffy.co.uk
>>>> and
>>>> the Wiki) into that format. I have looked at DocBook, and it looks
>>>> like
>>>> it would fit our needs.  It would be easy to get DocBook files into
>>>> svn,
>>>> and the HTML generated looks OK.
>>>
>>> For the web site, it might be nice to use the existing look. This may
>>> require a simple script to process the output of whatever you choose,
>>> or you could write it as HTML fragments which get turned into the read
>>> pages. I have a number of scripts which will help.
>> Right. I believe there are ways of 'skinning' docbook conversion to
>> HTML, to make it look like we want. Some added benefits will be improved
>> navigation controls, etc.
>
> Sounds good.
>
> What tools will developers need to use them properly?
For updating the docs: I'm using XMLMind's XML Editor, which is free
(beer). It's a bit of a learning experience, but once you get past the
slightly cluny interface, it works OK. Better than hand-editing XML. Ick.

For generating different types of docs, I'm looking into the best tools
to have at hand. I think it would be better if the distribution packages
contain the converted docs, not just DocBook, so users won't have to
install conversion tools (whatever we settle on).

We could generate HTML and PDF (if we want to), as well as man pages
(for the daemons and config files).

On a related note: Is there a Windows format comparable to man-pages?
>
>>>
>>> Once a format and arrangement has been chosen, we need to adjust the
>>> release scripts to include it, and depending on the format, run an
>>> appropriate pre-processor to make them readable.
>>>
>>> I suggest
>>>
>>>   [trunk|whatever]/documentation/boxbackup
>>>
>>> as a location for the documentation. This is to preserve the idea that
>>> multiple distributions can be built from the same source tree.
>> Sounds good. Do I need special privileges to check into svn?
>> Username/Password?
>
> Yes. I will allocate them as required. Perhaps you'd like to
> coordinate and apply diffs from those without SVN commit access?
Sure, I can take diffs, etc.

Thanks,
Per

-- 
Per Reedtz Thomsen | Reedtz Consulting, LLC | F: 209 883 4119
V: 209 883 4102    |   pthomsen@reedtz.com  | C: 209 996 9561
GPG ID: 1209784F   |  Yahoo! Chat: pthomsen | AIM: pthomsen