Quick guide to writing newbieDoc articles using lyx

Chris Lale

       chrislale@users.sourceforge.net

      

Revision History
Revision 0.018th March 2004Revised by: cl
Initial release. Lots still to do. The $ and # prompts need attention, especially in the section on installing apps. Also to finish the newbieDoc lyx reference document referred to below.
Revision 0.0212th March 2004Revised by: cl
Added a subsection describing how to reconfigure lyx after installing the newbieDoc lyx files.

lyx is a WYSIWYM (What You See Is What You Mean) document processor. If you can use a word processor you can use lyx. lyx is normally used to create LaTeX documents, but you can export documents to DocBook SGML format or DocBook XML format. This document describes the use of lyx to produce newbieDoc DocBook SGML. The exported SGML can be rendered into HTML using sgmltools-lite in the usual way. The instructions in this document are known to work lyx version 1.3.3 running in Debian 3.0 (Woody).

Table of Contents
1. The newbieDoc development environment using lyx
1.1. Install the applications
1.2. Install the newbieDoc lyx files
1.3. lyx layout files for newbieDoc
1.4. NewbieDoc template
1.5. CSS styles
1.6. Making the newbieDoc styles available in lyx
2. “Hello world!” the basic SGML document
3. “Hello world!” using lyx
3.1. Why use lyx to produce SGML?
3.2. Getting started using a newbieDoc template
3.3. lyx layouts and the list of styles
3.4. Modify the document information
3.5. Add the content using lyx styles
3.6. Generate and view SGML code
3.7. Generate and view the HTML web page
3.8. Generate HTML using the dsssl style-sheet
4. What next?
A. Appendix: About this document
A.1. Copyright information
A.2. Latest version
A.3. Bugs, errors and mistakes
A.4. Spelling, punctuation and grammar
A.5. Conventions used in this document

1. The newbieDoc development environment using lyx

1.1. Install the applications

NoteDebian specific
 

Debian uses apt or dpkg to install packages. Other distributions may use different tools to install software.

1.1.1. sgmltools-lite

Install sgmltools from your normal Debian source - your sources are listed in the file /etc/apt/sources.list. Open a terminal window eg gnome terminal. Switch user (su) to user Root, then install sgmltools-lite using apt. 

$ su 
Password: ****** 
# apt-get install sgmltools-lite

1.1.2. lyx (preferably 1.3.3 or higher).

Earlier versions should work, but I have not tested any. If you are not using Debian you can get the latest version from http://www.lyx.org.

Download the file lyx-qt_n.n.n-n_i386.tar.gz to a temporary directory. The number n.n.n-n is the version number. Move to the temporary directory. Extract the Debian package from the tarball. As user Root, install lyx with dpkg. 

# tar -xzvf lyx-qt_n.n.n-n_i386.tar.gz 
# dpkg --install lyx-qt_n.n.n-n_i386/lyx-qt_n.n.n-n_i386.deb

1.2. Install the newbieDoc lyx files

The newbiedoc-lyx-files_n.nn.tar.gz file contains newbieDoc lyx layout files, a newbieDoc lyx template and an enhanced version of the newbieDoc CSS style sheet.

Download the file lyx-qt_n.n.n-n_i386.tar.gz. The number n.n.n-n is the version number. Unpack the tarball in a temporary directory. 

# tar -xzvf newbiedoc-lyx-files_n.nn.tar.gz

1.3. lyx layout files for newbieDoc

The .layout and .inc files can be placed either in ˜/.lyx/layouts (local user only) or in /usr/share/lyx/layouts (system-wide for all users).

1.3.1. System-wide installation as user Root

Installed this way, all users will be able to use these lyx layouts. Copy the files to /usr/share/lyx/layouts/. 

# cp newbiedoc-lyx-files_n.nn/lyx-layout-files/* /usr/share/lyx/layouts/

1.3.2. Local installation as a normal user

Installed this way, only the user installing the lyx layouts will have access to them. Exit from user Root first, then copy the files to ˜/.lyx/layouts/. 

# exit 
$ cp newbiedoc-lyx-files_n.nn/lyx-layout-files/* ~/.lyx/layouts/

1.4. NewbieDoc template

Templates can be placed either in /usr/share/lyx/templates (system-wide for all users), or in ˜/.lyx/templates (local user only).

For a system-wide installation, put the file newbiedoc-lyx-template.en.lyx into the directory /usr/share/lyx/templates/. Alternatively, for a single user put it somewhere in your the user's home directory - usually ˜/.lyx/templates. (You can change LyX's template search path later from within LyX: Edit -> Preferences -> Paths.)

1.4.1. System-wide installation as user Root

# cp newbiedoc-lyx-files_n.nn/newbiedoc-template \
/newbiedoc-lyx-template.en.lyx /usr/share/lyx/templates/

1.4.2. Local installation as a normal user

Exit from user Root if necessary 

# exit
$

Copy the file 

$ cp newbiedoc-lyx-files_n.nn/newbiedoc-template \
/newbiedoc-lyx-template.en.lyx ~/.lyx/templates

1.5. CSS styles

NewbieDoc HTML pages look for a CSS style sheet (named nd-style.css) in the root directory. The root directory is either the system's root (/), or the document directory (eg /var/www/) if you are viewing web pages via a web server.

The newbieDoc Lyx styles use some extra CSS styles not available in the current version of nd-style.css. The extra styles are

If you want to use these extra styles, you must hard-code them into your final HTML files.

1.5.1. Hard-coding the extra styles into the final HTML file

Open the HTML file in a text editor and find <LINK REL="STYLESHEET" TYPE="text/css" HREF="/nd-style.css">. Insert the text below immediately after it.

This is the code immediately before the inserted text. 

    "><LINK
REL="STYLESHEET"
TYPE="text/css"
HREF="/nd-style.css">

Insert this extra HTML code. 

<!-- Extra styles needed for LyX-generated newbieDoc html files -->
<STYLE TYPE="text/css">
<!-- 
b.COMMAND               {font-style:bold;}
tt.FILENAME             {font-family: monospace;}
SPAN.APPLICATION        {font-variant: small-caps;}
PRE.SYNOPSIS            {
                        background-color: #ffffcc;
                        border:solid;
                        border-color: #009999;
                        border-left: solid #009999 20px;
                        border-right: solid #009999 0px;
                        border-top: solid #009999 0px;
                        border-bottom: solid #009999 0px;
                        padding-left: 15pt;
                        font-family: sans-serif;
                        }
//-->
</STYLE>
<!-- End of extra styles needed for LyX-generated newbieDoc html files -->

This is the code immediately after the inserted text. 

</HEAD
><BODY

1.6. Making the newbieDoc styles available in lyx

When you have finished copying the files to their destinations, run lyx. Reconfigure the new configuration using Edit -> Reconfigure from the menu bar, exit lyx and run a new instance of lyx. Thats it! 

Menu bar:    Edit -> Reconfigure

Menu bar:    File ->Exit

2. “Hello world!” the basic SGML document

Here is a very basic SGML document taken from the newbieDoc DocBook guide (http://newbiedoc.sourceforge.net/metadoc/docbook-guide.html). 

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
 <article>
  <sect1>
   <title> Hello world message </title>
   <para>
    Hello world!
  </para>
 </sect1>
</article>

It soon gets bigger when you add in all the other tags that go at the head of a newbieDoc document. The easiest way to manage the complexity in lyx is to use a template (see below).

3. “Hello world!” using lyx

3.1. Why use lyx to produce SGML?

lyx provides an easy way to produce an SGML document. If you can use a word processor you will find lyx very easy to pick up. You can find a lot of information about SGML in the newbieDoc DocBook Guide (http://newbiedoc.sourceforge.net/metadoc/docbook-guide.html).

3.2. Getting started using a newbieDoc template

Open a new document from lyx's menu bar. 

Menu bar:     File -> New from Template -> newbiedoc-lyx-template.lyx -> OK

3.3. lyx layouts and the list of styles

Using lyx is very like using a word processor. It operates on paragraphs - you create a paragraph every time you press the <ENTER> key. Section headings are often called 'commands' by lyx. Body text is usually either an 'environment' or a 'paragraph'. It is easiest just to think of them all as paragraphs.

Each paragraph is formatted in a particular lyx style. You chose the style form the drop-down list of styles in the top left-hand corner of the lyx window. A 'layout' is a collection of styles.

3.4. Modify the document information

Substitute your own information in the template's place-holders:

3.5. Add the content using lyx styles

This is how to produce a simple article with only one section and one paragraph of standard text. Position the insertion point (flashing vertical bar) at the end of the document. Create a new line by pressing the <ENTER> key.

Select 'Section' from the list of styles. The drop-down styles list is the left-most button in the button bar. Enter the title 'Hello world message' (without the quotes) and press the <ENTER> key. 

Drop-down styles list:    Section

LyX main window:    Hello world message

Enter a short paragraph using the Standard style. (Standard is the default style, so just go ahead and type.) 

Drop-down styles list:   Standard

LyX main window:   Hello world!

That's it! Remember to save the file (hello-world.en.lyx). 

Menu bar:   File -> Save -> hello-world.en -> Save

3.6. Generate and view SGML code

Generate DocBook SGML using lyx's 'Export' command. From the menu bar: 

Menu bar:     File -> Export -> DocBook

lyx produces a file with the same name (hello-world.en ) but with a .sgml extension in the same directory as the lyx source file. You can view hello-world.en.sgml with a text editor: 

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<article lang="en"> <!-- DocBook file was created by lyx 1.3 See http://www.lyx.org/ for more information -->
<!--newbiedoc-lyx-template.en.lyx, newbiedoc-lyx-template.en.sgml (version 0.01), Copyright (c) March 2004 Chris Lale <feedback.chrislale@coolscience.co.uk>. Permission is granted to copy, distribute and/or modify this document with no Invariant Sections, with no Front-Cover texts and with no Back-Cover Texts under the terms of the GNU Free Documentation License, version 1.1 or any later version, published by the Free Software Foundation. A copy of the license can be found at http://www.fsf.org/copyleft/fdl.html. -->
   <title> Page header (except first page) </title> 
   <articleinfo> 
     <title> Article title </title> 
     <author> 
         <firstname> Your-firstname </firstname> 
         <surname> Your-surname </surname> 
         <affiliation>
            <address> 
               <email> your-account@your-provider </email>
            </address>
         </affiliation>
      </author>
      <revhistory>
         <revision> 
            <revnumber> 0.01 </revnumber> 
            <date> 8 March 2004 </date> 
            <authorinitials> xx </authorinitials> 
            <revremark> Eg Initial release; brief note of changes to previous version.</revremark>
<!-- Insert subsequent revision information here. (Add these lyx layouts: Revision, Date, Initials and RevisionRemark.) -->
         </revision>
      </revhistory>
      <abstract> 
         <para> This is a short summary. It should include a statement such as: known to work with Debian 3.0 (Woody). </para>
      </abstract>
   </articleinfo>
   <sect1> 
      <title> Hello world message </title> 
         <para> Hello world! </para>
   </sect1>
</article>

lyx has added the DTD (Document Type Declaration) at the top. Then it has declared an article written in English (lang=”en”). It has also added a comment to say that this is a DocBook file created by lyx.

The article's header is contained between <title></title> tags, and the article title is between <articleinfo><title></title></articleinfo> tags.

The section's title is contained by <title></title> tags, and the following standard text is contained by <para></para> tags. Both these containers are contained within <sect1></sect1> first-level section tags. Finally, the whole article is contained by <article></article> tags.

3.7. Generate and view the HTML web page

You can transform your .sgml file into a number of different formats by using sgmltools-lite. (If you want to know more, read about sgmltools' back-ends in its manual - the command is man sgmltools.)

Open a terminal window (eg gnome terminal). Move to the directory containing both ( hello-world.en.lyx and hello-world.en.sgml). Execute this command: 

$ sgmltools -b onehtml hello-world.en.sgml

The result is another file in your working directory. The new file is hello-world.en.html and you can view it in a web browser. The HTML article has only one section: “Hello world message”. 

Web browser:    File -> Open -> hello-world.en.html -> OK

Hello world message
Hello world!

3.8. Generate HTML using the dsssl style-sheet

You can make your document look just like those on the newbieDoc website. Use sgmltools as before but specify the newbiedoc-onehtml.dsl style-sheet. 

sgmltools -b onehtml -s newbiedoc-onehtml.dsl hello-world.en.sgml

The new web page should now include a table of contents. 

Web browser:    View -> Reload

Table of Contents
1. Hello world message
1. Hello world message
Hello world!

4. What next?

You should now be able to produce a basic newbieDoc article quickly and easily. I expect that you will soon want to use other layouts and some in-line elements in your documents. (lyx handles some inline elements well eg URL links, tables and graphics. It is not so good with filename, command or application.) The newbieDoc lyx reference might be a good starting place (http://newbiedoc.sourceforge.net/web/newbiedoc-lyx-reference.en.html).

Good Luck! If you found this document useful, please let me know .

A. Appendix: About this document

A.1. Copyright information

Copyright ©2004 Chris Lale . Permission is granted to copy, distribute and/or modify this document with no Invariant Sections, with no Front-Cover texts and with no Back-Cover Texts under the terms of the GNU Free Documentation License, version 1.1 or any later version, published by the Free Software Foundation. A copy of the license can be found at http://www.fsf.org/copyleft/fdl.html.

A.2. Latest version

You can get the latest version of this document from http://newbiedoc.sourceforge.net.

A.3. Bugs, errors and mistakes

If you find any errors, omissions etc, please let me know via the newbieDoc Discussion list or .

A.4. Spelling, punctuation and grammar

I have written this document in English. I have used American spellings for some technical terms eg 'program' where these have become widely accepted.

You can find guides to English spelling, punctuation and grammar at http://www.cral.ac.uk/guidelines/.

A.5. Conventions used in this document

A.5.1. Ellipsis

Three dots ...

A.5.2. Directory trees

A trailing forward slash (/) indicates that this is a directory, not a file.

A.5.3. Command line prompts

A '$' at the start of a line indicates that the rest of the line is input from a normal user. A '#' indicates that the Root user inputs the rest of the line.

A.5.4. File names, application names, package names and screen text

Filenames, application names, package names and text displayed by a console or terminal window look like this. 

my-file.txt
my-directory
/my-path/my-directory/
my-application
my-package
This is some terminal text.

Filenames, application names, package names and text displayed in an X window look like this. 

my-file.txt
my-application
my-package
This is some text in an X window.

A.5.5. Commands

Commands issued from a terminal look like this. Use of the <ENTER> key is implied but not shown. 

$ my command

This example shows a command issued in an X application. 

Menu bar:    File -> Close