The Linux Documentation Project HOWTO Generator

Version 0.51 2004-05-23
Welcome to the LDP HOWTO Generator. By following through this form you will be able to generate the skeleton of your new HOWTO, customised to your particular needs. Examples of markup used can be found in the HOWTO Template SGML source along with the resulting HOWTO Template HTML output.

Note1: This Generator requires JavaScript.
Note2: Currently this is in Beta, most of the planned functionality is implemented, and the while the functionality is tested I would like more people to test this.
Please read the home page for updates.

Heading Definition

All HOWTOs have to have a number of fields defined in order to be usable by others and also to be easily maintained. The following fields are therefore mandatory:

Title
This will be the title of your HOWTO. For practical reasons it should not be more than one line (72 characters) long, preferrably less. It is important to be precise as well as concise.
Author
Your name(s)
Email
The email address you wish to be contacted at. HOWTOs are long lived documents, make sure your email address is equally durable. If needed the Linux Documentation Project can provide an email address, inquire for more information.
Version
Input a version number and date, for instance "V0.01". Version number is free format.
Date
Input a date, for instance "2000-05-11". Recommended date format is ISO standard for dates:"YYYY-MM-DD".
Primary Category
Chose the category that best fits your HOWTO. This will be used in categorising and in generating lists of HOWTOs. If no category fits chose the last category which is No Fit and someone will help you.
Keywords
A string of comma separated keywords that will aid search engines in locating your document.
Index
A single word used in creating indices. Use a word as descriptive of your HOWTO as possible. This word can also be the file name of the saved contents of this Generator.
Oneliner
A single line used for brief description in indices. Be as descriptive of your HOWTO as possible.

Abstract

All HOWTOs have an abstract, a single, brief paragraph that should tell your readers what this HOWTO is going to be about. Avoid using linebreaks.




HOWTO Body

Having defined the heading the time has come to the main body of the HOWTO. It is divided into sections and sub sections but here we will only do sections and just a few sub sections. This will give you the pattern to flesh out the rest of the document. Suggested titles are in editable boxes where appropriate, entire sections can be removed if you feel they are not needed for your topic.

Do keep in mind that this is just a quick start template based system that suggests a few more or less common conventions; this should not be regarded as a straightjacket.

1. Introduction

As the title suggests, an introduction. Expand on the abstract, give the background, be creative.


1.1 Copyright

All documents are copyrighted and it is up to the author to determine how their documents are to be distributed. For the LDP to be able to distribute your document as part of the body of works that it contains it is necessary that the copyrights allow this by being one of the free copyrights of which there is a few to chose from. Additionally you can roll your own but to be effective you have to know how copyright laws work.

An overview of several copyright licenses for documentation as well as software can be found at GNU.
To be accepted into The Linux Documentation Project the document has to be licensed according to either GFDL, Creating Commons or TLDP copyright, for more information please look at the licensing section of the Author Guide.
GFDL

GNU Free Documentation Licence

This is the license recommended by GNU for documentation.

This document is Copyright © <date><name>. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
CCSA

Creative Commons Attribution-ShareAlike 1.0 License

This is a recommended used for documentation.

You are free:
  • to copy, distribute, display, and perform the work
  • to make derivative works
  • to make commercial use of the work
Under the following conditions:
Attribution. You must give the original author credit.
Share Alike. If you alter, transform, or build upon this work, you may distribute the resulting work only under a license identical to this one.
  • For any reuse or distribution, you must make clear to others the license terms of this work.
  • Any of these conditions can be waived if you get permission from the author.

Other

Rolling your own


1.2 Disclaimer

We live in the age of lawyers, a disclaimer can save you legal problems, court cases and bankrupcy. This is not a joke. As always there is number of choices:
Simple

Simple Disclaimer

This is one used a number of places.

Use the information in this document at your own risk. I disavow any potential liability for the contents of this document. Use of the concepts, examples, and/or other content of this document is entirely at your own risk.

All copyrights are owned by their owners, unless specifically noted otherwise. Use of a term in this document should not be regarded as affecting the validity of any trademark or service mark.

Naming of particular products or brands should not be seen as endorsements.

You are strongly recommended to take a backup of your system before major installation and backups at regular intervals.
None

None

If you feel you need no disclaimers you can check this box.
Other

Rolling your own


We are now finished with the fixed formats header and are ready to fill in the main contents of this HOWTO. Each chapter below has a title as well as a small text field with the title repeated. If you are not satisfied with the proposed title you can change it in the small single line text box, making it the title of your own HOWTO.

Furthermore if you do not need the chapter at all you can remove it by unchecking the checkbox at the right edge which removes the chapter by commenting it out.

You can also change the level of a chapter from section to subsection or subsubsection. Note that the next few introductory chapters are given a default setting of subsection while the rest are given a default value of section.

1.3 News

Chapter type: Section Subsection Subsubsection
Enable this chapter
This is where you make a summary of news and recent updates to your document. For a new document this isn't expected to be much. When a HOWTO exceeds 20 pages it takes more than a casual read to find the updates. This is where you help your readers with that, alerting them to specific and important news. A pointer to where to get the latest version would also be useful. Many authors keep the latest version on their own home pages too.



1.4 Credits

Chapter type: Section Subsection Subsubsection
Enable this chapter
It is always nice to acknowledge people who help you with inputs, it is also regarded by many as important in the Linux world new economy. Example:

In this version I have the pleasure of acknowledging

corff (at) ZEDAT.FU-Berlin.DE
dwood (at) plugged.net.au
lcl (at) spiretech.com
kgh12351 (at) nifty.ne.jp
dave (at) lafn.org
name (at) site.org

Also Somecompany is acknowledged for sending me documentation on their gizmos as well as permission to quote from the material. These quotes have been approved before appearing here and will be clearly labelled.
Scramble the addresses so email harvesters cannot get addresses from your HOWTO and then spam people. That has happened in the past.


1.5 Translations

Chapter type: Section Subsection Subsubsection
Enable this chapter
Not everyone speaks English, pointers to translations are nice. Also your translators tend to give very important inputs. Example:

German Translation by someone (at) somewhere.de
Swedish Translation by someone (at) somewhere.se
French Translation by someone (at) somewhere.fr
Chinese Translation by someone (at) somewhere.cn
Italian Translation by someone (at) somewhere.it



When manually editing the HOWTO afterwards, you are recommended to insert hyperlinks to respective translations.

2. Structure

Chapter type: Section Subsection Subsubsection
Enable this chapter
A quick overview on how all parts fit together in the structure. Here I use an example from my Multi Disk HOWTO.

As this type of document is supposed to be as much for learning as a technical reference document I have rearranged the structure to this end. For the designer of a system it is more useful to have the information presented in terms of the goals of this exercise than from the point of view of the logical layer structure of the devices themselves. Nevertheless this document would not be complete without such a layer structure the computer field is so full of, so I will include it here as an introduction to how it works.




3. Technologies

Chapter type: Section Subsection Subsubsection
Enable this chapter
Introduction of technology for the newbie with a few references to detailled works. Remember that not everyone has Internet access so you have to explain in sufficient details so even the newbie can get by.

4. Implementation

Chapter type: Section Subsection Subsubsection
Enable this chapter
Now your readers should have a sufficient knowledge of what this is about and now we come to the hands on of implementing your clever scheme.

5. Maintenance

Chapter type: Section Subsection Subsubsection
Enable this chapter
Few systems and designs are maintenance free, here you explain how to keep the system running.


6. Advanced Issues

Chapter type: Section Subsection Subsubsection
Enable this chapter
You can get most things up and running in a quick and dirty fashion, useful for testing and getting used to how things work. For more serious use you would need to be a little more advanced. This is the place to explain it all, if applicable.

7. Troubleshooting

Chapter type: Section Subsection Subsubsection
Enable this chapter
Many problems can be solved by a simple structured approach, analysing the symptoms, finding the cause and determining the solution.


8. Further Information

Chapter type: Section Subsection Subsubsection
Enable this chapter
A HOWTO cannot describe everything, some times the user has to venture out on the net to get more information or just updates. Here is the place to tell where and how. Some suggestions are:



9. Getting Help

Chapter type: Section Subsection Subsubsection
Enable this chapter
Your reader might still end up in a situation where extra help is needed from someone else, perhaps on the net. In order to get fast and efficient help it is best first to get some details on your system. What details matter depends on type of problem. For disk problems you need to know the disk controllers etc, for networking problems you have to know what ethernet card is used and version of drivers etc. Here is the place to suggest what details to have ready when asking for help.


10. Concluding Remarks

Chapter type: Section Subsection Subsubsection
Enable this chapter
Just summing up... Also a place for general recommendations.


11. Questions and Answers

Chapter type: Section Subsection Subsubsection
Enable this chapter

Check the newsgroups and try to determine some frequent problems and cover them here. Again an example from my HOWTO:

This is just a collection of what I believe are the most common questions people might have. Give me more feedback and I will turn this section into a proper FAQ.

Q:How many physical disk drives (spindles) does a Linux system need?

A: Linux can run just fine on one drive (spindle). Having enough RAM (around 32 MB, and up to 64 MB) to support swapping is a better price/performance choice than getting a second disk. (E)IDE disk is usually cheaper (but a little slower) than SCSI.



12. Bits and Pieces

Chapter type: Section Subsection Subsubsection
Enable this chapter
This is basically a section where I stuff all the bits I have not yet decided where should go, yet that I feel is worth knowing about. It is a kind of transient area.

13. Examples

Chapter type: Section Subsection Subsubsection
Enable this chapter
Example designs and sample configuration files and other relevant details is always handy. Keep large samples at the end to avoid breaking the flow of the HOWTO reading. Small samples are useful within the main body of the HOWTO.




Finish

You are now ready to convert your epic HOWTO into an SGML file. The entries in the boxes above will be compiled when pressing the compile button below and the resulting SGML code will be outputted to the text box below that button.

When you start the compilation the status field of your browser tracks where in the compilation process you are. On a 1GHz Pentium it should take about a second. When finished the status bar should display the string LinuxDoc SGML Compilation Done. If the process hangs and does not finish, please contact the author with as much information as possible, preferrably with the information in the JavaScript Console if available.

Your next step then will be to copy the entire content of that box and paste it into a text editor and save the contents to a file. Filename is suggested to be the Index word you filled in at the top of this form.



Output of the compilation; select this and paste into an editor and save it.

List of errors and warnings: