This section shows how to get involved in writing your own LDP documentation. Getting and setting up the tools, making contact with the LDP in general, and distributing what you know to all the Linux users out there.
If you are a new to the LDP and want to pick up an unmaintained HOWTO or write a new HOWTO or mini-HOWTO document, contact the HOWTO coordinator at linux-howto@metalab.unc.edu. This is to make sure the HOWTO coordinator can know who is working on what documentation. Also note that all HOWTO submissions must be in SGML format (currently using the LinuxDoc DTD). The mini-HOWTO submissions may be made in either SGML or HTML formats, but only SGML-formatted submissions will be included in printed versions of the HOWTOs.
There are a few mailing lists to subscribe to so you can take part in how the LDP works. First is ldp-discuss@lists.linuxdoc.org, which is the main discussion group of the LDP. To subscribe, send a message with the subject reading "subscribe" to ldp-discuss-request@lists.linuxdoc.org. To unsubscribe, send an e-mail with the subject of "unsubscribe" to ldp-discuss-request@lists.linuxdoc.org.
Download the sgmltools package from http://www.sgmltools.org/, or directly from your distribution. The source files from sgmltools.org is in source code format, so you will have to compile the source code for your machine. Using a pre-built package for your distribution is easier, as you don't have to compile it and potentially run into compilation issues (that is, if you're not a coder).
With RedHat, the sgmltools is included with the distribution. If not, you can download it from ftp.redhat.com or any of its mirrors as part of the main distribution.
If you're using Debian, it too has sgmltools in the standard distribution. If you don't have the package installed, you can use the apt-get command to download and install the package for you:
# apt-get install sgml-tools
For more information on the Debian package, you can look at http://www.debian.org/Packages/stable/text/sgml-tools.html
If compiling from source, all you need to do is:
# tar -zxvf sgmltools-x.x.x.tar.gz # cd sgmltools-x.x.x # ./configure # make # make install
Replace sgmltools-x.x.x
with the actual version of the sgmltools package
you're using. The current version as of this writing that supports LinuxDoc
is 1.0.9. The version that supports DocBook is 2.0.2. Both are available at
the above web site.
Once the tools are installed, you have a number of commands available to you.
sgmlcheck file.sgml
- Checks the syntax of a given document.
sgml2html file.sgml
- Converts an SGML file into HTML. Creates a file.html
file that contains the Table Of Contents, then creates file-x.html
files where
x
is the section number.
sgml2rtf file.sgml
- Converts an SGML file into Rich Text Format (RTF).
Creates two files, the first being file.rtf
that contains the TOC, and a file-0.rtf
that contains all the sections.
sgml2txt file.sgml
- Converts an SGML file into ASCII text. The TOC and
all sections are all put into file.txt
.
sgml2info file.sgml
- Blah SGML blah INFO, used by the info command. All
output is sent to file.info
.
sgml2latex file.sgml
- Blah SGML blah TeX.
sgml2lyx file.sgml
- SGML yadda LyX graphical editor. This is great if you
have pre-generated SGML files and want to convert them for use in LyX.
Much like HTML, you can write SGML by hand, once you know all the markup codes you want to use. This section will go over as many of these codes as possible, along with practical examples of each. A nice place to start would be the SGML source for this document, which is available at the web site in the Introduction. As the SGML may be processed differently depending on the file format you go to, I'll try to list some things to know about as you're writing.
To start a new document, create a new file in your favorite ASCII editor and start with this:
<!doctype linuxdoc system>
This defines the document type (LinuxDoc in our case) that the SGML processor will use when it renders the file in an output format. Nothing is rendered from this tag.
Next you need to enclose the rest of your work in <article>
and </article>
tags. This signifies the start of the content (or article, eh?). If you're
familiar with HTML, this is similar to enclosing all your content with <html>
and </html>
.
The first part of the content should contain general information about the rest of the content. This would be similar to the first few pages of a book, where you have a title page (title of the work, author, date of publication, table of contents, and so on).
The title of the content is enclosed in <title>
and </title>
tags. The author is specified in <author>
and </author>
tags. The
date uses <date>
and </date>
.
The two remaining sections are the <abstract>
and </abstract>
tags, which provide an executive summary of what the content is about, and
the <toc>
tag, which specifies the location of the table of contents.
The TOC is automatically generated by the SGML processor. We'll get into sections
later on.
Now, how does it all look together? Taking a nice bit of SGML code (that is, what was used to create this document) you'll see:
<!doctype linuxdoc system> <!-- LinuxDoc file was created by LyX 1.0 (C) 1995-1999 by <markk> Fri Aug 27 09:42:28 1999 --> <article> <title>HOWTO HOWTO </title> <author>Mark F. Komarinski </author> <date>Aug 27, 1999 </date> <abstract>Getting a new LDP author up and running with tools, ideas, and conventions used by the LDP </abstract> <toc>
This bit of content created the main page you see when you look at this document in RTF or HTML format, listing all the information on one page.
In order to build the Table of Contents, you need to have something to build with. Sections in the case of SGML is the same as chapters in traditional publishing. You have multiple sections, and each section can have a subsection, and each of those can have a subsection and so on.
Starting your document with sections is great as it lets you create an outline of the major topics you want to cover. You can then break down these major sections into gradually smaller sections, until you have a nugget of information you can write about in a few short paragraphs. In writing this document, I actually started this way.
Sections are one of the few sets of SGML tags that don't require to be
closed. That is, there is no </sect>
tag. Nor do you have to worry about
numbering. The SGML processor will handle it all when you render the SGML into
something else.
Sections are started with <sect>
tags. A new section is started with
each <sect>
tag. The first section is numbered 1.
Creating subsections (like 1.1) is done with the <sect1>
tag. It
also starts with 1.
Sub subsections (1.1.1) is done with the <sect2>
tag, and also starts
with 1.
When the SGML processor comes across the <toc>
tag, it runs through
the rest of the document and builds the Table Of Contents based on the number
of section tags within it. Sections are numbered and listed in the TOC and
then used in the rest of the document. Sub subsections (1.1.1) do not show
up in the TOC, but are put in emphasized text if possible.
Writing paragraphs of content is just like in HTML. Use a <p>
tag
to specify a new line, and start writing. SGML will ignore whitespace such
as tabs, multiple spaces, and newlines. When SGML comes across a <p>
tag, it starts a new paragraph. Proper SGML has you put in a </p>
to
end the paragraph.
Every now and then you need a touch of text to stand out from the others.
Either to highlight code or to list a command name.
The first (emphasizing
text) is done with <em>
and </em>
tags. Typewriter text (the second
example) is done with <tt>
and </tt>
tags.
There are two forms of doing lists under SGML. First is an enumerated list, where each item in the list is numbered (like sections) starting with 1.
The code for the above list looks like this:
<enum> <item>This is the first entry in the enumerated list. <item>This is the second. <item>Third. </enum>
The <enum>
tag specifies that the following items are going to be
enumerated.
The other method of writing lists is itemized, where each item merely has a star, or circle, or dot, or some other method of itemizing each item.
The above code looks like this in raw SGML:
<itemize> <item>This is the first entry in the itemized list <item>This is the second. <item>Third. </itemize>
As you can see, the <item>
tag is the same for enumerated and itemized
lists.
A third form of lists is the description lists. This has a term being described, and the phrase that describes it.
The Linux Documentation Project
Standard Generalized Markup Language
The code to create the above descriptions is:
<descrip> <tag>LDP</tag>The Linux Documentation Project <tag>SGML</tag>Standard Generalized Markup Language </descrip>
This isn't quite the same as itemized or enumerated lists, but you have
the entire list surrounded by a tag (<descrip>
and </descrip>
)
and each item in the line that is a word being defined is enclosed in <tag>
and </tag>
. The remainder of the line is taken to be the definition of
the word.
Sometimes you just need to print some text the way you write it. For this,
you can use the <verb>
and </verb>
tags to enclose a paragraph
in verbatim mode. Spaces, carriage returns, and other literal text (including
special characters) are preserved until the </verb>
.
The following is verbatim text .
Also in SGML is the ability to handle Universal Resource Locators (URL) of any kind. Note that this would only work when exported to HTML mode, but you'll get some use out of this tag in other formats (does RTF use it too?).
A URL doesn't have an end tag, but puts its information within the <url>
tag itself. Here is a URL that points to the LDP homepage:
http://www.linuxdoc.org/. And here's the
code to create it:
<url url="http://www.linuxdoc.org/" name="http://www.linuxdoc.org/">
The url="http://www.linuxdoc.org/"
tells the browser where
to go, while the contents of the name
="http://www.linuxdoc.org/"
tells the browser what to print out to the screen. In this case, the two are
similar, but I could create a URL tag that looks like this:
<url url="http://www.linuxdoc.org/" name="LDP">
And then looks on the page like this: LDP.
While URLs are great for linking to content outside the LDP document you're
working on, it's not that great for linking within the content itself. For
this, you use the <label>
and <ref>
tags. The <label>
tag
creates a point in the document where you want to refer back to later on, almost
like a bookmark. Creating the <label>
is easy. Find the point where you
want to refer back to later on, and insert the following:
<label id="Introduction">
You have now created a point in the content that you can refer to later on as "Introduction". This label actually appears in this SGML work at the front of the document. When you want to refer back to that point later on (say here), you insert the following SGML:
<ref id="Introduction" name="here">
and the SGML will know to put in a link called "here" (see above) that links back to the location of the Introduction section.
The other part of references is indexing. Since LDP documentation is usually published on paper as a large collection of documents, there needs to be a way of building the index at the back of the book, based on words and subjects.
Much like HTML, you will need to escape many non-alphanumeric characters to prevent the SGML processor from interpreting them as SGML code. Here's a list of the SGML codes used. More are listed in the sgmltools User's Guide located at http://www.sgmltools.org/guide/guide.html
I'm still gushing about LyX. Okay, so I'm a bit biased towards this application because I really like it. It provides the power of writing SGML with the ease-of-use of a regular word processor. It's not a WYSIWYG program, but more WYSIWYM (What You Get Is What You Mean) application, since what you see on the screen isn't necessarily what happens after the SGML processor is done with it.
To create a LinuxDoc document with LyX, download and install the application.
Make sure you have TeX and sgmltools installed first (see
Installing the Tools for more information
on this). Once complete, start up LyX and select "file->new from template..."
Select "Templates" then click on linuxdoctemplate.lyx
and you'll have a template
document set up, with most of the header information that an LDP document should
have. Change the data to suit your need (that is, fill in the Title, Author,
Date, Abstract, and so on) and then start writing. The pull down menu in the
upper left hand corner can be used to select types of content (standard, itemized
and enumerated lists, sections). The exclamation point is used to emphasize
text, and you can either click it and begin typing in emphasized mode, or highlight
text with the mouse and click on it to emphasize the highlighted text. Many
other features of SGML can be found under the Insert menu bar. You can insert
URL locations, cross references, index entries, and other kinds of data. When
complete with your documentation, you can save it in LyX format, then export
to LinuxDoc and have the file saved with a .sgml extension. That file is then
ready to be checked with sgmlcheck and rendered to the formats you want.
I have this thing about Emacs. I don't use it, and it doesn't get me peeved. Anyone with more Emacs experience would be very helpful.
If there are other SGML tools out there, or even commercial ones that the LinuxDoc DTD can be used with to create LDP documentation, please let me know.
At this time, the LDP does not have a shared repository for you to store your content online. Hopefully this will change. There are a few good reasons for using CVS:
Before you distribute your code to millions of potential readers there are a few things you should do.
First, be sure to spell-check your document. Nothing says "Hi, I'm stupid!" faster in the Internet-land than misspellings. Most utilities that you would use to write SGML (emacs, LyX, other text editors) have plug-ins to perform a spell check. If not, there's always the ispell program, installed in just about every distribution. Also use the sgmlcheck command with sgmltools to verify you have correct SGML tags.
Second, get someone to review your documentation for comments and factual correctness. The documentation that is published by the LDP needs to be as factually correct as possible, as there are millions of Linux users that may be reading it. If you're part of a larger mailing list talking about the subject, ask others from the list to help you out.
Third, create a web site where you can distribute your documentation. This isn't required, but is helpful for people to find the original location of your document.
In order for an LDP document to be accepted by the LDP, it must be licensed to allow for free (as in beer) distribution and publishing. As an author, you may retain the copyright and add other restrictions (for example, you must approve any translations or derivative works). A sample license is available at http://www.linuxdoc.org/COPYRIGHT.html. If you choose to use the boilerplate copyright, simply copy it into your source code under a section called "Copyright and Licenses" or similar. Also include a copyright statement of your own (since you still own it). If you are a new maintainer for an already-existing HOWTO, you must include the previous copyright statements of the previous author(s) and the dates they maintained that document.
Once your LDP document has been reviewed by a few people and you took into account their comments, you can release your document to the LDP in general. Send an e-mail to ldp-submit@lists.linuxdoc.org with your source code. Within 24 hours you should find out if it was accepted and posted to the main LDP site.