Workbook uploaded to wiki -- anyone know Docbook or LaTeX?

Shawn Wells shawn at redhat.com
Mon Apr 1 21:57:53 UTC 2013


On 4/1/13 4:13 PM, Maura Dailey wrote:
> On 04/01/2013 12:20 PM, Shawn Wells wrote:
>> Hey Guys,
>>
>>     The workbook used from the March session is now uploaded to the 
>> wiki:
>> https://fedorahosted.org/scap-security-guide/
>>
>>     Reference "See a Workbook..." link under the "To see how this 
>> works" section.
>>
>>     Goal is still to convert to docbook or some other multi-author 
>> friendly format. Does anyone have experience in those formats (I 
>> don't!) and willing to lend a hand/point me in the right direction? 
>> Right now the source content is in ODT.
>>
>> -Shawn
>> _______________________________________________
>> scap-security-guide mailing list
>> scap-security-guide at lists.fedorahosted.org
>> https://lists.fedorahosted.org/mailman/listinfo/scap-security-guide
>
> I'll start off by saying that at a high level, DocBook and LaTeX give 
> document authors extremely similar development environments. Someone 
> that knows one format can probably pick up the other. However, the 
> goals of both are a little different. LaTeX is more powerful for 
> formatting documents because it can tap into its TeX roots, but a lot 
> of the power it gives document authors would be wasted here (fine 
> control over text formatting, the ability to easily embed figures and 
> equations, etc.). DocBook is more portable, because it doesn't have 
> any formatting built in. Formatting must be done through XSLT and 
> other transforms, just like any other XML document. I think DocBook 
> makes the most sense for this project because developing in DocBook 
> will remove formatting from the picture. Also, many Linux 
> distributions are already using DocBook for documention, including Red 
> Hat, Fedora, and Ubuntu.
>
> I haven't written anything from scratch in DocBook, but I've edited 
> existing files. It's fairly clean to edit, but much wordier than HTML. 
> Since you're at Red Hat, you should ask your documentation team if 
> they have any tool recommendations or stylesheets for you to try. How 
> horrible is LibreOffice's save as docbook option, by the way? I've 
> seen a few references online where people have used it successfully, 
> although they usually claim there is some cleanup work that has to be 
> done before it's fit for publication. In theory, it should be possible 
> to get a very clean translation, since the Open Office format actually 
> is XML.

I've uploaded the ODT and SaveAs DocBook formats here, in case anyone 
wants to take a stab:
http://people.redhat.com/swells/.scap/

I'm using LibreOffice 3.4.4 and found that the XML generated is 
incomplete. I'm not sure if the error is on my end or that the format 
doesn't convert nicely. Regardless, based off your comments it would 
appear DocBook would be the better format.

Anyone up for creating a pretty SSG XML stylesheet?


More information about the scap-security-guide mailing list