DocBook can be a bit intimidating for the uninitiated. This page is intended to help those unfamiliar with DocBook to get started contributing to LfL.
Contents |
If you are already familiar with other markup languages, such as HTML, you should be able to adjust quickly to using DocBook. The basic idea is the same: you use tags to mark words, sections, paragraphs, etc., with a specific role or appearance. Although the specific tags do not match other languages, the idea is the same. The Style Guide includes an appendix about the markup so you can quickly find out what tags are available.
LfL offers a template to make it easier to get started. Find it in SVN in trunk/common/xml/. Download the template, copy it under an appropriate name for your lesson into trunk/books/en/xml, then modify it for your lesson. Most text just needs to go in <para> tags.
If you have trouble with the tags, just do your best and remember to validate it. You can ask on list for general or specific questions. It takes practice to learn the ins and outs of XML and even in house people still find it challenging occasionally.
You have a lot of options for editing XML files. They are a basic text file that should have UTF-8 encoding. This means they can be modified with any text editor. Those of us at SUSE are still investigating XML editors, especially those in a WYSIWYG style. We do not have any recommendations at this time beyond text editors, but we'll let you know as soon as we get other results. Any input from the community regarding easier editors for those inexperienced with XML as text files would be appreciated.
There are several XML editors that are not WYSIWYG-like but simplify the task of writing in XML:
If you still can't get the hang of XML but want to contribute a lesson to LfL, you can write a plain text file. Check this file into SVN in trunk/books/en/txt. Once your text-based lesson is ready, send an e-mail to the mailing list to ask for volunteers to convert it to XML for you. Once your lesson has been converted to DocBook, you'll have to work with XML to maintain it, but it isn't as hard when the structure is already there.
In order to make your contributions show up in the manual, you need to include them to the main book file lessons4lizards.xml with the <xi:include> tag. This should be pretty straight forward as lessons4lizards.xml already contains numerous examples.
Unless you have committed your changes, they are only available on your local machine. To make them available for the public, you have to upload them to the SVN. Please follow the instructions at Uploading Contributions.
© 2008 Novell, Inc. All Rights Reserved.
