-\begin_layout Section
-Using LyX with SGML-Tools (aka LinuxDoc)
-\end_layout
-
-\begin_layout Standard
-by
-\noun on
-Paul Evans
-\end_layout
-
-\begin_layout Subsection
-Overview
-\end_layout
-
-\begin_layout Standard
-LinuxDoc is a document class available in LyX if you have the
-\family typewriter
-sgml-tools
-\family default
- package installed.
- You can use it to produce documents in the so-called Standardized General
- Mark-up Language (SGML) in the particular format used by the Linux Documentatio
-n Project.
- That is obviously helpful if you are contributing to that project.
- You can use the SGML format with the
-\family typewriter
-sgml-tools
-\family default
- package of scripts and programs (to produce other formats, including LaTeX,
- HTML, plain text, man pages and\SpecialChar \ldots{}
-).
- You may therefore prefer to use this document class if you want to write
- something that can be easily translated into other formats.
-\end_layout
-
-\begin_layout Standard
-You will find that LinuxDoc has fewer layout options than the other text
- classes in LyX.
- This is mainly so that the translations into other formats have a chance
- of making some sense.
- In this section we describe:
-\end_layout
-
-\begin_layout Itemize
-how to setup and use a document in LinuxDoc
-\end_layout
-
-\begin_layout Itemize
-how to use the tags in LinuxDoc to layout your document
-\end_layout
-
-\begin_layout Itemize
-how to use the SGML packages to produce the various formats
-\end_layout
-
-\begin_layout Itemize
-how to sort out some problems.
-\end_layout
-
-\begin_layout Subsection
-Preparing and using a LinuxDoc document
-\end_layout
-
-\begin_layout Subsubsection
-Getting started
-\end_layout
-
-\begin_layout Standard
-You start by selecting the LinuxDoc class using the
-\family sans
-\bar under
-D
-\bar default
-ocument\SpecialChar \menuseparator
-
-\bar under
-S
-\bar default
-ettings
-\family default
- dialog.
- Then you will find that there are fewer paragraph environments than for
- most other classes.
- You can see them on the pull down box on the left of the tool bar.
- How to use them is described in section\InsetSpace ~
-
-\begin_inset LatexCommand ref
-reference "sec:sgmlparas"
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Standard
-You
-\emph on
-must
-\emph default
- enter a title for the document, followed by an author, marking each with
- the appropriate paragraph environment.
- If you don't do this, you will get errors when you try to print the file.
- You can then enter the date and an abstract.
- The document proper must start with a Section paragraph environment rather
- than any standard layout.
-\end_layout
-
-\begin_layout Standard
-After that you can prepare a document as usual using the available range
- of paragraph environments.
- See section\InsetSpace ~
-
-\begin_inset LatexCommand ref
-reference "sec:sgmlparas"
-
-\end_inset
-
- for the full list and their uses.
-\end_layout
-
-\begin_layout Subsubsection
-Output from LinuxDoc
-\end_layout
-
-\begin_layout Standard
-You can print and save these documents in the normal way.
- To use the other features of the SGML package you need to save your document
- as LinuxDoc; this is a version in which the document is translated into
- the basic sgml tags.
- Use
-\family sans
-\bar under
-F
-\bar default
-ile\SpecialChar \menuseparator
-
-\bar under
-E
-\bar default
-xport\SpecialChar \menuseparator
-Linu
-\bar under
-x
-\bar default
-Doc.
-
-\family default
- You will get a file with the same name and a
-\family typewriter
-.sgml
-\family default
- extension rather than a
-\family typewriter
-.lyx
-\family default
- extension.
- See\InsetSpace ~
-
-\begin_inset LatexCommand ref
-reference "sec:sgmloperate"
-
-\end_inset
-
- on how you than make use of this file.
-\end_layout
-
-\begin_layout Subsection
-Using the paragraph environments in LinuxDoc
-\end_layout
-
-\begin_layout Subsubsection
-The Structure of a LinuxDoc Document
-\end_layout
-
-\begin_layout Standard
-There is a formal structure for LinuxDoc which limits how you can place
- tags.
- There are two parts to all documents:
-\end_layout
-
-\begin_layout Description
-Header: this is everything up to the first time you insert a Section layout
- marker.
- It can include title, author, date, abstract and ToC.
- You must include the first two.
-\end_layout
-
-\begin_layout Description
-Body: from the beginning of the first section onwards.
- All other tags are allowed.
-
-\end_layout
-
-\begin_layout Subsubsection
-The LinuxDoc Paragraph Environments
-\end_layout
-
-\begin_layout Standard
-\begin_inset LatexCommand label
-name "sec:sgmlparas"
-
-\end_inset
-
-Here is a list of all the tags you will find listed on the layout bar in
- the order they come there, with some comments where the purpose or use
- is not obvious:
-\end_layout
-
-\begin_layout Itemize
-
-\family sans
-Standard:
-\family default
-
-\family roman
-works as described in [cross reference]
-\end_layout
-
-\begin_layout Itemize
-
-\family sans
-Title
-\family default
-: This will appear at the top left of the document when printed, above a
- heavy horizontal rule, although you will not see this on the LyX screen.
-\end_layout
-
-\begin_layout Itemize
-
-\family sans
-Section, Subsection, Subsubsection, Paragraph and Subparagraph:
-\family default
- all do what you would expect and in the usual order.
- Whether they are numbered or not is controlled by the
-\family sans
-Section\InsetSpace ~
-number\InsetSpace ~
-depth
-\family default
- setting.
- You cannot get the equivalent number free versions in any other way; there
- is no
-\family sans
-Section*
-\family default
- or similar
-\end_layout
-
-\begin_layout Itemize
-
-\family sans
-Enumerate:
-\family default
- As usual this produces a numbered and indented list as described in the
-
-\emph on
-User's Guide
-\emph default
-.
-\end_layout
-
-\begin_layout Itemize
-
-\family sans
-Itemize:
-\family default
-
-\family roman
-Again much the same as in the other classes: see the
-\family default
-
-\family roman
-\emph on
-User's Guide
-\emph default
-.
-\end_layout
-
-\begin_layout Itemize
-
-\family sans
-Description
-\family default
-: As explained in the
-\emph on
-User's Guide
-\emph default
-.
- Remember that if you want the bold element at the start of a description
- to be more than one word then you need to put protected spaces between
- the words.
-
-\end_layout
-
-\begin_layout Itemize
-
-\family sans
-Verbatim:
-\family default
- As usual.
-\end_layout
-
-\begin_layout Itemize
-
-\family sans
-Code: similar to the LyX-Code
-\family default
-
-\family roman
-environment
-\end_layout
-
-\begin_layout Itemize
-
-\family sans
-Author
-\family default
-: Anything you mark with this will appear on the left of the heading of
- the document, under the heavy rule.
-\end_layout
-
-\begin_layout Itemize
-
-\family sans
-Date:
-\family default
- Anything you mark with this will appear on the right of the heading under
- the rule.
- You do not have to make this a date.
- Any text can be entered, e.\InsetSpace ~
-g.
- a version number.
-\end_layout
-
-\begin_layout Itemize
-
-\family sans
-Abstract
-\family default
-: You can use this to produce a free standing paragraph after the author
- and date, and before the first section.
- You are only allowed one such paragraph.
-\begin_inset Foot
-status collapsed
-
-\begin_layout Standard
-
-\emph on
-Author's note.
-
-\emph default
- This needs checking ---
-\emph on
-pe.
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Itemize
-
-\family sans
-Displaymath
-\family default
-:
-\begin_inset Foot
-status collapsed
-
-\begin_layout Standard
-
-\emph on
-Author's note:
-\emph default
- I have not yet checked this ---
-\emph on
-pe.
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsubsection
-Other document features
-\end_layout
-
-\begin_layout Standard
-You can also use the
-\family sans
-Layout
-\family default
- menu to set fonts or to emphasis words.
- You can also use the table of contents as usual; see the corresponding
- section of the
-\emph on
-User's Guide
-\emph default
-.
- Although you will find some some other features on the menus e.\InsetSpace ~
-g.
- inserting footnotes.
- There is some doubt about whether these will work correctly.
-\begin_inset Foot
-status collapsed
-
-\begin_layout Standard
-
-\emph on
-Author's note:
-\emph default
- Again still checking to see whether this is my system
-\emph on
----pe.
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsubsection
-Cross references and HTML
-\end_layout
-
-\begin_layout Standard
-On the
-\family sans
-Insert
-\family default
- menu you will find two new options relating to the inclusion of URL addresses.
- If you use either option you will find some highlighted TeX code inserted
- into your document in three separate blocks with spaces available between.
- The blocks will be:
-\end_layout
-
-\begin_layout Quote
-
-\family typewriter
-
-\backslash
-htmlurl{
-\family default
- or
-\family typewriter
-
-\backslash
-url{
-\family roman
-
-\hfill
-space
-\family default
-
-\family typewriter
-
-\hfill
-}{
-\family roman
-
-\hfill
-space
-\hfill
-
-\family typewriter
-}
-\end_layout
-
-\begin_layout Standard
-You insert a full HTML tag between the first and second blocks.
- This can be
-\begin_inset LatexCommand url
-target "http://any.address"
-
-\end_inset
-
- or other valid tags such as
-\begin_inset LatexCommand url
-target "mailto:me@my.address"
-
-\end_inset
-
-
-\family typewriter
-.
-\family default
-Then y
-\family roman
-ou
-\family default
- insert some description between the second and third blocks.
- The differences are:
-\end_layout
-
-\begin_layout Itemize
-
-\family sans
-URL:
-\family default
-
-\family roman
-both the HTML tag and the description will appear in the document
-\end_layout
-
-\begin_layout Itemize
-
-\family sans
-HTML\InsetSpace ~
-URL:
-\family default
-
-\family roman
-only the description appears in the printed version
-\end_layout
-
-\begin_layout Subsection
-Using the LinuxDoc Sgml scripts
-\begin_inset Note Note
-status collapsed
-
-\begin_layout Standard
-This section is completely outdated.
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-\begin_inset LatexCommand label
-name "sec:sgmloperate"
-
-\end_inset
-
-You can use LinuxDoc as a text class without any additional scripts or programs,
- but there is not much point in doing this.
- All you will get is a document that looks like a
-\emph on
-Linux Documentation Project Howto
-\family sans
-\emph default
-.
-
-\family default
- To do the document translation you need to get and install the
-\family typewriter
-sgml-tools-1.0.x.tar.gz
-\family default
- (with
-\begin_inset Formula $x\geq3$
-\end_inset
-
-) package from
-\family roman
-the SGML-Tools WWW Page
-\family default
- at
-\end_layout
-
-\begin_layout LyX-Code
-
-\family roman
-\begin_inset LatexCommand url
-target "http://pobox.com/~cg/sgmltools"
-
-\end_inset
-
-
-\family default
-
-\end_layout
-
-\begin_layout Standard
-Alternatively, you can go to the
-\family typewriter
-sunsite
-\family default
- archive at
-\begin_inset Foot
-status collapsed
-
-\begin_layout Standard
-Note that, at the time of this writing (01/1998), version 1.0.3 of sgml-tools
- has not yet been made available at
-\family typewriter
-sunsite
-\family default
-.
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout LyX-Code
-
-\family roman
-\begin_inset LatexCommand url
-target "ftp://sunsite.unc.edu/pub/Linux/utils/text/sgml-tools-1.0.x.tar.gz"
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-
-\family roman
-The
-\family default
- file
-\family typewriter
-sgml-tools-1.0.x.tar.gz
-\family default
- contains everything that you need to write SGML documents and convert them
- to groff, LaTeX, HTML, GNU info, LyX, and RTF\SpecialChar \@.
-
-\end_layout
-
-\begin_layout Standard
-This package was renamed from
-\family typewriter
-linuxdoc-sgml-1.5.tar.gz
-\family default
- in January 1997.
-\end_layout
-
-\begin_layout Standard
-Follow the instructions in that package on how to install it and how to
- use it.
- All this has to be done outside of LyX, before you can use the
-\family sans
-\bar under
-F
-\bar default
-ile\SpecialChar \menuseparator
-
-\bar under
-E
-\bar default
-xport\SpecialChar \menuseparator
-as\InsetSpace ~
-LinuxDoc
-\family default
-
-\family roman
-option.
-\end_layout
-
-\begin_layout Subsection
-Troubleshooting LinuxDoc
-\end_layout
-
-\begin_layout Standard
-When you print or preview a LinuxDoc document some checking is done of the
- tags before LaTeX is run.
- Some errors are trapped here, especially those concerning the structure
- of the document.
- LyX may produce an error message, but not leave an error box in the document
- for you to open.
- You may have to look at the files directly to discover what is wrong.
- Most problems seem to come from the use of options that are not fully available
- in the text class.
-\end_layout
-
projects / lyx.git / commitdiff