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(a)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:
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?