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

[Ben Summers]

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?


>>
>>>
>>> Let me know what you think. I'd like to get started ASAP, with  
>>> figuring
>>> out the outlines for the books we need to produce.
>>>
>>> I'm going to be going over the Wiki and Ben's web site, to see if  
>>> I can
>>> categorize the pages (or even sections) into the books they  
>>> belong in.
>>
>> It would also be nice to have manual pages for the executables as  
>> well.
> That's a good idea. A bit of googling tells me that you can create
> man-pages from docbook as well, without any fuss.

Splendid.


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

Ben