GNU.WIKI: The GNU/Linux Knowledge Base

  [HOME] [HowTo] [ABS] [MAN1] [MAN2] [MAN3] [MAN4] [MAN5] [MAN6] [MAN7] [MAN8] [MAN9]

 


  David S. Lawyer
  v0.09, November 2007

  This is about how to write HOWTOs using the simple LinuxDoc markup.
  It's primarily for Linux Documentation Project authors (and future
  fledging authors who want to get started fast).  If you want to use
  the more difficult and complex DocBook markup (including XML) see the
  LDP Authoring Guide.
  ______________________________________________________________________

  Table of Contents


  1. Introduction
     1.1 If you want to start immediately
     1.2 Copyright and License
     1.3 Should you write a HOWTO ?
     1.4 Why I wrote this

  2. Information on Writing a HOWTO
     2.1 Copyright
     2.2 Choosing a topic

  3. The Format of HOWTOs
     3.1 Introduction

  4. Comparing LinuxDoc to DocBook
  5. Learning LinuxDoc
     5.1 Introduction
     5.2 Example 1 (file name: example1.sgml)
     5.3 Example 2 (file name: example2.sgml)
     5.4 Example 3
     5.5 LinuxDoc Quick Reference Sheet
        5.5.1 Header Part
        5.5.2 Body Layout
        5.5.3 Fonts
        5.5.4 Lists (nesting is OK)
        5.5.5 Links
        5.5.6 Newline, Verbatim, URLs
        5.5.7 Character Codes (macros)

  6. Getting/Using the LinuxDoc Software
  7. Errors and Error Messages
     7.1 Errors That Don't Create Error Messages
     7.2 Actual Error Messages

  8. Jargon in Error Messages
     8.1 Introduction
     8.2 Elements
     8.3 Literals and Delimiters

  9. Writing the HOWTO
     9.1 Before you start writing
     9.2 Guidelines
     9.3 Submitting the HOWTO, etc.

  10. More Information
  11. Appendix
     11.1 Old Problem of Escape Sequences in Text Output


  ______________________________________________________________________



  1.  Introduction

  1.1.  If you want to start immediately

  To only learn LinuxDoc, skip to  ``Learning LinuxDoc''.  If you want
  to start writing immediately, then you may try a "fill in the blanks"
  template which will generate LinuxDoc formatted output.  The LDP HOWTO
  Generator <http://www.nyx.net/~sgjoen/The_LDP_HOWTO_Generator.html>.
  You may use this to just start writing your Howto and then finish it
  later by using a text editor on your PC.


  1.2.  Copyright and License

  Copyright (c) 2001-7 by David S. Lawyer.  You may freely copy and
  distribute (sell or give away) this document.  You may create a
  derivative work and distribute it provided that you license it in the
  spirit of this license and give proper credits.  The author would like
  to receive your comments, suggestions, and plans for any derivative
  work based on this.


  1.3.  Should you write a HOWTO ?

  Do you know things about Linux for which no good free documentation is
  available and which would be useful to others?  Even if you don't know
  the subject well, you can still write about it if you're eager,
  willing, and able to learn more about it and have the time to do it.
  Can you write clearly using a word processor or editor?  Do you want
  to help thousands of others and let them read what you write at no
  cost to them?  Once you've written a document, are you willing to
  receive email suggestions from readers and selectively use this info
  for improving your HOWTO?  Would you like to have your writings be
  available on hundreds of websites throughout the world?  If you can
  answer yes to these, then you're encouraged to write something for the
  Linux Documentation Project (LDP).  But be warned that it may take
  more time than you expected.


  1.4.  Why I wrote this

  Why did I write this when there is already an "LDP Authoring Guide"?
  Well, the LDP guide is a long and detailed work.  If you want to get
  started quickly, you need something much simpler and shorter.

  Thanks to Matt Welsh for his example.sgml file which I used as a major
  source of info for the example sections.


  2.  Information on Writing a HOWTO

  2.1.  Copyright

  All HOWTOs and other LDP documents are copyright by the authors so the
  LDP doesn't have any special rights to your writing.  We only accept
  documents that have a license which  permits anyone to copy and
  distribute the document.  We encourage authors to also allow
  modification in their license.  This way, if the author stops
  maintaining a document, someone else can do so.  For more details see
  our Manifesto.


  2.2.  Choosing a topic

  If you are not sure what to write about, take look at some of LDP's
  documents including the ones in Unmaintained HOWTOs
  <http://www.tldp.org/authors/unmaint.html>.  Pick a topic you're
  interested in that needs good documentation.  If you find something
  already written and maintained that needs improvement, try to contact
  the author, first and make suggestions.  If you can't reach the
  author, look at the license and see if you're allowed to modify the
  document.  But even in the cases where you are not allowed to make
  modifications and improvements, you can just write a new document on
  the same topic from scratch, using a new outline new sources of
  information.


  3.  The Format of HOWTOs

  3.1.  Introduction

  Our HOWTOs are released to the public in various formats: Plain Text,
  HTML, PostScript, and PDF.  Instead of having to write the same HOWTO
  in all of these formats, just one HOWTO is written in a source format,
  DocBook or LinuxDoc, which gets converted by computer into all of the
  other formats.

  To get an idea of what a source format looks like, take a look at the
  source file of a webpage (if you haven't already).  You will see all
  sorts of words in <angle brackets>.  These are called tags.  These
  webpages (tags and all) are in html: Hypertext Markup Language.  The
  LDP uses formats something like this for its documents.

  The markup languages LDP uses meet the requirements of either Standard
  Generalized Markup Language (SGML) or XML.  The LDP now uses the
  following two flavors of sgml: LinuxDoc and DocBook as well as the
  DocBook flavor of XML.  Interestingly, it turns out that html is just
  another flavor of sgml (but some features people use in html violate
  sgml rules so it's not pure sgml anymore).

  This mini-HOWTO is all about using the simple LinuxDoc flavor of sgml.
  You may call it "LinuxDoc markup".  It can be converted by computer to
  html, plain text, postscript, pdf, and DocBook.  It's a lot easier
  than HTML or DocBook and you don't need a special editor for it as
  it's easy to type in the tags (or use macros for them) using your
  favorite editor or word processor.


  4.  Comparing LinuxDoc to DocBook

  Before reading this section it's best to have at least an elementary
  knowledge of tags in markup languages.  So if you don't know much
  about this, you may first want to look at ``Example 1'' for LinuxDoc
  markup.

  One way to compare is to inspect real HOWTOs at the LDP site.  Click
  on either DocBook Index
  <http://cvs.tldp.org/go.to/LDP/LDP/howto/docbook/> or LinuxDoc Index
  <http://cvs.tldp.org/go.to/LDP/LDP/howto/linuxdoc/> to find them.
  You'll notice that the DocBook docs are cluttered with tags while the
  LinuxDoc docs have far fewer tags and are thus more readable and
  easier to write and modify.  Some documents at LDP are marked up much
  more clearly than others so you should inspect at least a few
  documents.

  You may at first think that DocBook is more advanced since there are
  so many more tags but this isn't necessarily so.  If you create a
  document in LinuxDoc and convert it to DocBook (by computer) there
  will be many more tags in the DocBook version, including new tags that
  were not in the LinuxDoc version.  Why?  Because LinuxDoc permits the
  omission of tags while DocBook doesn't.  And in this way LinuxDoc is
  more flexible and advanced than DocBook.  Not only does LinuxDoc often
  allow the omission of end-tags like </title> but allows the omission
  of both start and end tag pairs.  For example, in LinuxDoc paragraphs
  are normally separated by blank lines instead of pairs of paragraph
  tags <p> (<para> in DocBook) so that paragraph tags are seldom needed.
  Another example is just after the start of a new section of a LinuxDoc
  document.  You just type in the title of the section after the <sect>
  tag while DocBook requires one to also enclose the title in a pair of
  <title> tags.

  When one runs a program to convert LinuxDoc to say HTML, the first
  thing the program does is to find all the omitted tags and add them to
  the document.  For example, a pair of tags are added which are
  equivalent to the pair of <title> tags after a <sect> tag (including
  the cases of <sect1> tags, etc.).  So in a sense, LinuxDoc also has a
  lot of tags, but they are hidden from the user to make the document
  both much easier to write and read.  In most cases, the author writing
  a document in LinuxDoc is unaware of the existence of most of the
  missing tags.  There's no need (in most cases) for the author to know
  about them since they exist only in the computer memory (or a
  temporary file) when the PC is converting LinuxDoc to some other
  format (like to HTML).  Well, it is possible to save a file showing
  the added tags but that is done mainly by programmers debugging the
  LinuxDoc computer code (or by people like me that are curious about
  how it works).

  The DocBook tags are often longer than the equivalent LinuxDoc tags
  such as <em> instead of <emphasis>.  For a short comparison see the
  author's website Comparison of DocBook to LinuxDoc
  <http://www.lafn.org/~dave/linux/ld_vs_db.txt>

  However, the fact that many tags are omitted when writing LinuxDoc
  (but are found by the software) is only one reason why LinuxDoc
  documents have fewer tags.  Another reason is that DocBook actually
  has many more tags to use than LinuxDoc does.  For example, LinuxDoc
  has just one tag for the author's name while DocBook has separate tags
  for the first middle and last names.  So in this sense DocBook is more
  powerful than LinuxDoc but in another sense it's weaker since it can't
  find missing tags.  The solution to this dilemma would be to merge
  LinuxDoc with DocBook so as to retain the advantages of each.  DocBook
  would then need to abandon it's current status as a "xml" language
  since xml prohibits the omission of tags, etc. while sgml allows it.

  One reason why omitted tags are not allowed in DocBook is that it
  makes it easier for programmers to write software to parse it and
  convert it to other formats.  There is no need for software capable of
  finding and adding missing tags.  But making it easier for
  programmers, makes it more difficult for the much large number of
  writers that have to use DocBook.

  There are special editors or word processors like Lyx and Bluefish
  that make it easier to type DocBook documents.  For example, Bluefish
  automatically adds end tags.  But for people who don't want to learn a
  new editor or word processor, LinuxDoc is a lot easier since one can
  type in the tags by hand or create a set of macros to insert the
  (<emphasis> tags.  I use the vim editor and if I type ;s it inserts
  the <sect1> tag.  ;r does <sect>, ;i does <item>, etc.  For the header
  tags on the first several lines of the document, I just copy them from
  another document and change the words after the tags.  Of course I
  don't need to change the author's name or email.  So a major advantage
  of LinuxDoc is that one can easily use it with the same editor or word
  processor that they currently use and know.

  Some people who don't understand the situation have advocated making
  DocBook about as easy as LinuxDoc by just using a subset of the
  DocBook tags.  This doesn't work because DocBook will still require a
  few times as many tags to get the same results due to the requirement
  of DocBook to not permit any omitted tags.

  In spite of the advantages of LinuxDoc, the number of people who use
  DocBook greatly exceeds the number using LinuxDoc partly because
  Linuxdoc was promoted by book publishers.  There's a program by Reuben
  Thomas (ld2db) which can convert LinuxDoc documents to DocBook.  It's
  not perfect and you will likely need to do some manual editing.  The
  LDP also automatically converts a LinuxDoc HOWTO to DocBook after you
  submit it.  It would be nice to have another program to automatically
  convert DocBook docs to LinuxDoc so they can be modified by people
  using the simpler LinuxDoc markup.


  5.  Learning LinuxDoc

  5.1.  Introduction

  LinuxDoc is a lot easier to learn than DocBook.  But most of what you
  learn about LinuxDoc would also be useful for DocBook.  So if you
  eventually decide to go for DocBook, most of the effort spent on
  learning LinuxDoc will not be wasted.

  One way to learn it is by examples.  I've written 3 example files
  ranging from easy to intermediate.  The contents of these files have
  been copied into this Howto.  To turn them into individual files you
  may cut them out (start with the first tag) and write them to files.
  Then you could try turning one into text by using say sgml2txt
  --pass="-P-cbou" some-example.sgml to see what it looks like.  Make
  sure the sgml file names end in .sgml.

  If you want to look at some real examples you can just go to an LDP
  mirror site, find the HOWTOs and select LinuxDoc SGML.  Or go to the
  main site directly: Howto Index (linuxdoc)
  <http://cvs.tldp.org/go.to/LDP/LDP/howto/linuxdoc/> Now for the first
  simple example.


  5.2.  Example 1 (file name: example1.sgml)



  <!doctype linuxdoc system>
  <article>
  <title>First Example (example1)
  <author>David S.Lawyer

  <sect> Introduction
  <p> This is a very simple example of "source" for the LinuxDoc text
  formatting system.  This paragraph begins with a paragraph tag (a "p"
  enclosed in angle brackets).  Notice that there are other tags, also
  enclosed in angle brackets.  If you don't see any tags, then you are
  reading a converted file so find the source file: example1.sgml (which
  contains the tags).

  This is the next paragraph.  Note that it is separated from the above
  paragraph by just a blank line.  Thus it needs no "p" tag in front of
  it.  The "p" tag is only needed for the first paragraph of a section
  (just after the sect-tag).  The file suffix: sgml stands for Standard
  Generalized Markup Language.  You are now reading the LinuxDoc flavor
  of sgml as specified in the very first line of this file.

  <sect> Tags
  <p> Tags are words inside angle brackets.  The "sect" tag above
  marks the start of a new section of this example document.
  "Introduction" was the first section and you are now reading the
  second section titled "Tags".  If this were a long document (like a
  book), a section would correspond to a chapter.

  Note that there are "article", "title" and "author" tags at the start
  of this article.  At the end of this article is an "/article" tag
  marking the end of this article.  Thus there is a pair of "article"
  tags, the first being the start tag and the second being the end tag.
  Thus this entire article is enclosed in a pair of "article" tags.  In
  later examples you'll see that there are other tags that come in pairs
  like this.   They affect whatever is between the pairs (start tag and
  end tag).  Any tag name which has "/" just before it is an "end tag".

  When this source code is converted to another format (such as plain
  text using the program sgml2txt) the tags are removed.  Tags only help
  the sgml2txt program make the conversion.  There are more tags to
  learn.  So once you understand this example1, please go on to the next
  example: example2.  You don't need to actually memorize the tags, as
  they will be repeated (but with little or no explanation) in later
  examples.
  </article>



  5.3.  Example 2 (file name: example2.sgml)



  <!-- This is a comment.  It's ignored when this source file gets
  converted to other formats.  -->
  <!-- The tag below says that this file is in LinuxDoc format -->
  <!doctype linuxdoc system>

  <article>

  <title>Second Example (example2)
  <author>David S. Lawyer
  <date>v1.0, July 2000

  <abstract>
  This is the abstract.  This document is the second example of using
  the Linuxdoc-SGML flavor of sgml.  It's more complex than the first
  example (example1.sgml) but simpler than the third example
  (example3.sgml).  After you digest this you'll be able to write a
  simple HOWTO using LinuxDoc.  End of the abstract.
  </abstract>

  <!-- The "toc" = Table of Contents.   It will be created here. -->
  <toc>

  <!-- Begin the main part of the article (or document) here.  The part
  above this is sort of a long header. -->

  <sect>This Second Example (example2.sgml)

  <p>Unless you're familiar with markup languages, you should first
  read example1.sgml.  You may want to run these example files thru a
  translator such as sgml2txt to convert them to text and notice how the
  result looks different than this "source" document with all its tags.

  <sect>Article Layout
  <sect1> Document Body

  <p> After the header comes the body of the document, consisting of
  nested sections marked by sect-tags.  Subsections are
  marked by sect1-tags.  Since this is the first subsection
  within the 2nd main section, it's becomes section 2.1.  Within a
  subsection marked by sect1 there may be sub-subsections like
  sect2.  There are even tags like sect3, sect4, etc., but you are
  unlikely to need them.  Note the the real tags must be enclosed in
  angle brackets < and >.

  <sect2> This is a sub-sub-section
  <p>
  It's 2.1.1.  Note that a "p" tag may be on a line by itself.  This
  doesn't change a thing in the resulting documents.

  <sect1>Document Header
  <p> One way to create a header part is just to copy one from another
  .sgml file.  Then replace everything except the tags with the correct
  info for your document.  This is like using a "template".

  <sect> More Features in example3
  <p> With the tags in this example2 you can write a simple short document
  a few pages long.  But for longer documents or for other important
  features such as putting links into documents, you need to study the
  next example: example3.  It will also show you how to create lists and
  fonts.
  </article>



  5.4.  Example 3



  <!doctype linuxdoc system>
  <!-- Note the mailto: after my name.  This allows the reader of html
  format to click on my email address to send me email -->

  <article>
  <title>Third Example (example3)
  <author>David S. Lawyer <url url="mailto:dave@lafn.org">
  <date>v1.0, July 2000
  <abstract>
  This document is the third example of using the LinuxDoc flavor of sgml.
  It's more complex than the second example.
  </abstract>
  <!-- Comment: toc = Table of Contents  -->
  <toc>

  <sect> Fonts
  <p>
  While they will not show up in a plain text output, they will work
  for other conversions.
  <bf>boldface font</bf>   <em>emphasis font</em>     <sf>sans serif</sf>
  <sl>slanted font</sl>    <tt>typewriter font</tt>   <it>italics font</it>
  There's another way to get these same fonts by enclosing the text in
  slashes like this: <bf/boldface font/    <em/emphasis font/
  <sf/sans serif/ <sl/slanted font/     <tt/typewriter font/
  <it/italics font/ Note that DocBook doesn't have font tags so it may
  be best not to use fonts if you plan to convert to DocBook.

  <sect> Links <label id="links_">
  <p> You may create links (something that html browsers may click on to
  go somewhere else).  They might just go to another part of this
  document (cross-references) such as to the "label" above, or they
  could go to a website on the Internet.

  <sect1> Cross-References
  <p> If you click on <ref id="links_" name="Links"> you will be taken to
  the start of the "Links" section above (which is labeled links_).
  The label id may be any word you choose but it's a good idea to avoid
  common words so that you can search for unique labels using your
  editor.  That's why I use links_ (with the underline).  The name of
  this link will be shown (in html format) as the name to click on.
  This name (Links) will also be present in the text rendition.

  <sect1> URL Links
  <p> If you click on <url url="http://www.tldp.org"> you will get
  to the Linux Documentation Project website.  The next link adds a name
  which people will click on: <url url="http://www.tldp.org"
  name="Linux Documentation Project">.  Using this second method, you may
  not even need to explain where the link leads to since it's obvious by
  the name.

  <sect> Prohibited Characters
  <p> Any word you type between angle brackets will be interpreted as a
  tag.  But what if you want to display a tag in a document?  For this
  you use a code word for the angle characters.

  You may use &lt for < and &gt for >.  lt = Less Than, gt =
  Greater Than.  For example, here's a p-tag: &lt;p&gt;.  Of
  course it doesn't actually start any paragraph, but it will appear in
  the converted document as <p>.  These codes all start with an &
  character.  The ; after the lt is to separate it.  It's not needed if
  there is a space after it.  For example: 3 &lt 4.  Actually, if
  you knew that its OK to use an unpaired > then you could have written
  <p> as &lt;p>.  This will not be mistakenly recognized as a tag
  since there is no opening <.  Actually 3 < 4 works fine too.

  There are other characters that you can't put into the document text
  directly.  For & in an AT modem command use: AT&amp;.  If other
  characters cause you trouble (they seldom will) see <ref id="ch_codes"
  name="Character Codes (macros)"> or the "guide" that comes with
  linuxdoc-tools or sgml-tools.

  <sect> Verbatim, Code & Newline
  <sect1> Verbatim
  <p> If you want to insure that it will look exactly like you typed it
  after it's converted  to other formats, use verbatim (verb).  This is
  useful for creating tables, etc.  But some things still get recognized
  as markup even though they are between verbatim tags.  This includes
  the macros starting with & and end tags with /.

  <tscreen><verb>
  % sgml2txt --pass="-P-cbou" example.sgml
  </verb></tscreen>
  The "tscreen" sets the font to typewriter and indents it nicely.

  <sect1> Code
  <p> This encloses computer code between two dashed lines.
  <tscreen><code>
  Put computer source code here
  </code></tscreen>

  <sect1> Newline
  <p> To force a newline use <newline>
  This sentence always starts at the left margin.

  <sect>Lists
  <p>
  This puts items into a list with a bullet at the start of each item.
  They start with the "itemize" tag.
  <itemize>
  <item> This is the first item in a list.
  <item> This is the second item
         <itemize>
         <item> Multiple levels (nesting) are supported.
         <item> The second item in this sublist
         </itemize>
         <enum>
         <item> Enumerated lists using <tt/enum/ also work.
         <item> This is item number 2
         </enum>
  <item> The final item in the main list
  </itemize>
  </article>



  5.5.  LinuxDoc Quick Reference Sheet

  5.5.1.  Header Part



       <!doctype linuxdoc system>
       <article>
       <title>Quick Reference Sheet
       <author>David S. Lawyer
       <date>v1.0, July 2000
       <abstract> abstract here </abstract>
       <toc> <!-- Comment: toc = Table of Contents  -->


  5.5.2.  Body Layout



       <sect> Chapter 1            Note: Put a <p> on the first line of
       <sect1> Subsection 1.1      each section (or subsection, etc.)
       <sect1> Subsection 1.2
       <sect> Chapter 2            Choose title names to replace "Chapter"
       <sect1> Subsection 2.1      "Subsection", etc.
       <sect2> Sub-subsection 2.1.1
       <sect2> Sub-subsection 2.1.2
       <sect1> Subsection 2.2
       </article>



  5.5.3.  Fonts

  There are two ways to get these:

  <bf>boldface font</bf>   <em>emphasis font</em>     <sf>sans serif font</sf>
  <sl>slanted font</sl>    <tt>typewriter font</tt>   <it>italics font</it>
  <bf/boldface/    <em/emphasis/     <sf/sans serif/
  <sl/slanted/     <tt/typewriter/   <it/italics/



  5.5.4.  Lists (nesting is OK)



       Ordinary unnumbered list:               Numbered list:
       <itemize>                               <enum>
       <item> First item                       <item> First item
       <item> Second item                      <item> Second item
       <item> etc.                             <item> etc.
       </itemize>                              </enum>



  5.5.5.  Links



          Cross-References:                            An Email Link:
       <ref id="links_" name="Links">     <url url="mailto:bob@tldp.org">



  5.5.6.  Newline, Verbatim, URLs



  To force a newline <newline>
  <tscreen><verb>
  <url url="http://www.tldp.org">
  <url url="http://www.tldp.org" name="Linux Documentation Project">.
  </verb></tscreen>



  5.5.7.  Character Codes (macros)

  You don't always need to use these.

  �  Use &amp; for the ampersand (&),

  �  Use &lt; for a left bracket (<),

  �  Use &gt; for a right bracket (>),

  �  Use &etago; for a left bracket with a slash (</)

  Use of these are optional and I seldom use them.

  �  Use `` and '' for opening and closing double quotes

  �  Use &shy; for a soft hyphen (that is, an indication that this is a
     good place to break a very long word to insert a hyphen for
     horizontal justification).

  Only use these if LinuxDoc complains about it or fails to generate
  them in the formated document.  I've seldom had to use them.

  �  Use &dollar; for a dollar sign ($),

  �  Use &num; for a hash (#),

  �  Use &percnt; for a percent (%),

  �  Use &tilde; for a tilde (~),

  �  Use &dquot; for ".


  6.  Getting/Using the LinuxDoc Software

  You could write a LinuxDoc document without having any LinuxDoc
  software.  However, it's likely that it would contain some errors in
  the tags (or their use) so that it would be returned to you for
  correction.  Even if there were no errors, the results might not not
  look quite right.  So it's best for you to have the software to
  convert your source code on your computer.

  The Debian distribution of Linux has a linuxdoc-tools package.  There
  is also a rpm package for non-Debian distributions.  It was formerly
  called sgml-tools.  Don't use the sgmltools-2 package which is
  primarily for DocBook-sgml.

  To use linuxdoc-tools you run converter programs on the *.sgml files.
  For example for versions after 0.9.21-0.8 to get text output, type:
  "sgml2txt -f --blanks=1 my-HOWTO.sgml".  For earlier versions due to a
  bug you must substitute --pass="-P-cbou" for -f.  (If interested, see
  ``Old Problem of Escape Sequences in Text Output'' for more info on
  this bug.)   To get html output,type: "sgml2html my-HOWTO.sgml".  If
  it shows errors, it will show the line number and the column number
  where the error is in the source file.  Typing "man -k sgml" should
  show you a number of other programs with a one-line description of
  each but not all of them are for linuxdoc-sgml.


  7.  Errors and Error Messages

  7.1.  Errors That Don't Create Error Messages

  A major error is to forget to put a <p>. tag after a section heading.
  Then there is no end to the section heading and all the following
  paragraphs become part of the section heading and get into the table
  of contents.  Linuxdoc should be improved to spot this error.  To spot
  it manually, look at the table of contents in html or text format.
  Fixing it requires just adding the missing p-tag.


  7.2.  Actual Error Messages

  When you are running the linuxdoc program (sgml2html or sgml2txt for
  example) you are likely to see some error messages.  You need to edit
  your document and fix the errors.

  Omission of closing quotes is a common error.  If you get an error
  message that makes no sense and notice that at the error location are
  some quotes (" ") that are OK, then the likely error is that you have
  previously typed an opening quote with no closing quote.  Like: <....
  id="my home page > so linuxdoc thinks that the next quote, which may
  be many paragraphs after the missing quote location, is the closing
  quote.  Then after the false closing quote it expects a > to finish
  the tag but doesn't find one.  To find and fix the missing quote, just
  search backwards for a ".

  A single error can cause a lot of error messages.  In the example
  above, a number of tags may be inside erroneous quotes that shouldn't
  have been inside any quotes.  So the linuxdoc will not find these
  tags.  As a result, it will not know that a certain tag is open and if
  it finds a closing tag it will tell you that that tag was not open.
  For example, if the <itemize> tag was missed, then  <item> tags may
  make no sense to linuxdoc and it will report an error for each such
  tag found beyond the false closing quote.

  One thing you should know is that the tag names are not case sensitive
  so the error messages will show tag names in upper case (capital
  letters) even though you typed them in lower case.

  To understand the error messages better requires an understanding of
  the jargon on sgml which you don't really need to learn unless you get
  errors which you can't seem to get fixed and you don't understand the
  error message.  The following sector is about such jargon.


  8.  Jargon in Error Messages

  8.1.  Introduction

  You really shouldn't need to read this section unless either you're
  either having problems or you're curious about how sgml and linuxdoc
  work.  Error messages may contain words like "element", "entities,
  "attribute", "literal", and delimiter".  Various elements, entities
  and attributes  are defined for linuxdoc in the "Data Type Definition"
  (or dtd) for LinuxDoc.  The dtd doesn't define them in sentences but
  uses a rather cryptic format to define their syntax (but not their
  semantics).



  8.2.  Elements

  An "element" is something like a tag.  But it's a much broader
  concept.  Elements exist not only in linuxdoc but in all sgml
  languages like say html.  Your entire document is partitioned into
  elements.  But elements are nested, which is to say that some elements
  may occur within other elements.  If you use the <article> tag for
  your document, then all of the document is the <article> element,
  except for the very first tag which says that what follows is
  linuxdoc.  And within this article element are nested many other
  elements.

  For example, each paragraph is an element, even though the paragraphs
  are separated from each other by blank lines instead of tags.  But
  there's an implicit tag surrounding each paragraph and the software
  that parses a linuxdoc writing will actually insert these missing
  tags.  It will also insert end tags (closing tags) where you didn't
  need to write any.  In this way, linuxdoc saves you a lot of time.  So
  an element will consist of a start tag and the end tag (for this start
  tag) and everything in between (often including other elements and
  their tags).  Note that the tags omitted but they still are implicitly
  there.  In some cases, a tag doesn't enclose anything, like the url
  tag for a link to the internet.  Such tags are themselves elements.
  Within the article-element are found sect-elements (sections) starting
  with <sect>.  Then within sect-elements are often found sect1-elements
  (subsections), etc.

  There are few cases where an element occurs but the use of both start
  and end tags are optional.  So even if you have no such tags in your
  document, the parts of the document that they should have enclosed are
  still elements for the missing tags.


  An entity is like a macro definition.  For example, one could define
  the name "list" to mean the various types of lists.  Then this name
  list is used only in the dtd to specify, for example, that a list may
  occur within a paragraph.  It's just a shorthand for the writer of a
  dtd.  This kind of an entity is never used in a linuxdoc document.
  But there's also another type of entity that can be used inside a
  document and that's one that defines a special character such as
  amp;etago for </ (end tag open).   You would use this when you want
  to, for example, put </article> in the middle of a sentence to explain
  what it means so that the software that converts LinuxDoc doesn't
  think it's really at the end of the article.


  8.3.  Literals and Delimiters

  A "literal" is a name of something, like the name one clicks on in an
  html link.  It may be one or more words long.  A delimiter is what
  separates something from something else.  For a "quote" the last " is
  the closing delimiter.  So for name="my website" the literal is 'my
  website' and the delimiters of this literal are the two " marks, the
  first " an opening delimiter and second " a closing delimiter.  So if
  a "literal is missing a closing delimiter it means that you neglected
  to put an ending " after a name.


  9.  Writing the HOWTO

  9.1.  Before you start writing

  First join the discuss list by going to  <www.en.tldp.org> and submit
  your proposal to this list.  If you're taking over an unmaintained
  HOWTO, contact the former author.  This may required by the copyright-
  license but you should do it out of courtesy even it it's not
  required.


  9.2.  Guidelines

  These are mostly by Tim Bynum (a former HOWTO coordinator).

  �  Be sure and use an accepted format (such as LinuxDoc :-).

  �  Try to use meaningful structure and organization, and write
     clearly. Remember that many of the people reading HOWTOs do not
     speak English as their first language.

  �  Make sure that all of the information is correct. I can't stress
     this enough. When in doubt, speculate, but make it clear that
     you're only guessing.  I use ?? if I'm not sure.

  �  Make sure that you are covering the most recent version of the
     available software.

  �  Consider including a "FAQ" section or sections called "Common
     Problems" or "Trouble Shooting".

  �  Be sure to copyright it in your name and include a license which
     meets the requirements stated in the LDP manifesto.

  �  Use the standard header with title, author, and date (including a
     version number).  See ``Example 3''

  �  Lastly, be prepared to receive email questions and comments from
     readers.  How much you help people is up to you but you should make
     use of good suggestions and reports of errors.  You may also get
     some "thank you for writing this" email.

  9.3.  Submitting the HOWTO, etc.

  After you have written the HOWTO, email the SGML source to
  submit@tldp.org.  Then all you need to do is to keep the HOWTO up-to
  date by submitting periodic updates to the same email as you used for
  the first edition.


  10.  More Information

  There's a HOWTO: Linuxdoc-Reference that covers it in much greater
  detail than this mini-HOWTO.


  11.  Appendix

  11.1.  Old Problem of Escape Sequences in Text Output

  Prior to version 0.9.21-0.8 there was a bug for the case of text
  output.  For sgml2txt, the option --pass="-P-cbou" was needed to get
  pure text output since otherwise if you used the -f option, you got
  text output which put emphasis on words and letters by the use of
  escape sequences and overstriking.  An example of a bullet made by
  overstriking is +^Ho which on a printer would type +, then backspace
  (^H), and then type o over the existing +.  This doesn't seem to work
  on display terminals (they can't overstrike).  Note that even if you
  have the most recent version, you'll still get this unwanted output if
  you fail to use the -f option.

  In case you are interested, the --pass passes the -P-cbou option to
  the groff program (used by sgml2txt) and the -P option of groff passes
  the -cbou options to grotty (a post-processor for groff) forcing
  grotty to generate just plain text output.  See the grotty man page.
  In brief: -c avoids escape sequences but allows overstrikes but -bou
  prohibits overstrikes when the -c option is used.  The result is no
  overstrikes and no escape sequences in the output.  -b prohibits
  overstrikes to make a character look bold;  -u prevents overstrikes
  for underlining; and -o prohibits other kinds of overstrikes like the
  bullet example above.  An alternate way to eliminate overstrikes is to
  use the -f option with sgml2txt but you still have to pass the -c
  option to grotty to eliminate escape sequences unless you have the
  newer version.

  What a mess it was!  The default should probably be plain text so that
  all of this passing of options wouldn't be needed.  I've finally got
  them to fix this so after about mid-2007 you can use just the -f
  option instead of --pass="-P-cbou".  If you get these escape sequences
  and overstrikes in your output file but use the Linux "cat" command to
  display the text, it looks great.  But using pagers or editors on the
  text output file usually results in the escape characters being eaten
  so you see a bunch of unwanted characters in your text that were
  supposed to be part of escape sequences.  In some cases, pagers can
  display certain overstrikes OK but editors (like vim) don't.  So
  eliminating all overstrikes permits you to use any editor or pager to
  read it.







  All copyrights belong to their respective owners. Other site content (c) 2014, GNU.WIKI. Please report any site errors to webmaster@gnu.wiki.