Reference for writing newbieDoc articles using lyx

Chris Lale

       chrislale@users.sourceforge.net

      

Revision History
Revision 0.0115 April 2004Revised by: cl
Initial release

This is a collection of information for anyone using lyx to write DocBook articles for the newbieDoc project (http://newbiedoc.sourceforge.net). The instructions in this document are known to work lyx version 1.3.3 running in Debian 3.0 (Woody).


Table of Contents
1. Quick start
2. How to build the newbieDoc template from scratch
2.1. Copyright licence information
2.2. Page header
2.3. Article title
2.4. Author's name
2.5. Affiliation
2.6. Revision history
2.7. Abstract
3. lyxstyles used in newbieDoc
3.1. Section
3.2. Subsection
3.3. Subsubsection, Paragraph and Subparagraph
3.4. Standard text (<para></para>)
3.5. Lists
3.6. Code, screen and xscreen
3.7. Character data (CDATA)
3.8. Comments
3.9. HTML metadata keywords
4. Inline elements
4.1. Emphasis style
5. Tables
5.1. Inserting a table
5.2. Links
5.3. Specify a language
6. ERT (Evil Red Text)
6.1. Command
6.2. Filename
6.3. Combined Command and Filename
6.4. Application
6.5. Other SGML styles
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
B. Appendix: Analysis of lyx styles and layout files

1. Quick start

If you want to get writing straight away you should look at the quick guide to writing newbieDoc articles using lyx. The quick guide explains how to install the software that you need, how to write a simple article using lyx and how to derive an HTML page from a lyx file.

This article describes the features available in the lyx “newbieDoc article (DocBook)” document class.


2. How to build the newbieDoc template from scratch

You will not want to do this very often, if at all. Just use the newbieDoc template as a starting point for your article. However, for the curious, this is how I built the template using the newbieDoc article (DocBook) lyx styles.


2.1. Copyright licence information


2.1.3. Create the SGML file

Export the file to DocBook and render the resulting SGML file.

Menu bar:    File -> Export -> DocBook
    

The resulting SGML file is called build-template.en.sgml. Here is the SGML resulting from an export to DocBook:

<!-- newbiedoc-lyx-reference.en.lyx, newbiedoc-lyx-reference.en.sgml,
Copyright (c) 2002 your name, your email address, newbieDoc project,
http://newbiedoc.sourceforge.net. 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, with no
Front-Cover Texts, and with no Back-Cover Texts. A copy of
the license can be found at
http://www.fsf.org/copyleft/fdl.html. -->
    

This copyright notice will appear in the SGML document as well as the document. It will not appear in the rendered HTML document. You must include it separately, perhaps in an appendix. You can check this by generating the HTML file from the SGML file using sgmltools.

$ sgmltools -b onehtml -s newbiedoc-onehtml.dsl build-template.en.sgml
    

2.4. Author's name

Press the <ENTER> key to start a new style. First choose Firstname from the drop-down list of styles. Enter your first name.

Drop-down styles list:    Firstname

LyX main window:    Author's first name:     Your first name
   

Repeat for your surname.

Drop-down styles list:    Surname
LyX main window:    Author's surname:     Your surname
   

2.5. Affiliation

ImportantThe order matters
 

The Affiliation style is like a wrapper. You must add Affiliation after you have entered its contents (Email).


2.6. Revision history

ImportantThe order matters
 

The revision details must be entered first, then they are wrapped in Revision number. There may be more than one Revision number. They must all be wrapped in Revision history.


2.6.4. Revision

Now add the wrapper. Place the insertion point (vertical, flashing bar) just to the left of your Date entry, and press the <ENTER> key. The insertion point appears on a new, blank line between Author's email: and Revision date: .

LyX main window: 

     Author's email:     your-address@example.com
|
     Revision date:     today's date
    

Select Revision from the drop-down list of styles and enter a revision number. If this is the first draft of your article you could give it the revision number 0.01.

Drop-down styles list:    Revision
    

The Revision details now look like this:

LyX main window:

      Revision (number):      0.01
      Revision date:     today's date
      Reviser's initials:     you
      Revision remark:     A meaningful comment
    

Wrap the Revision with Revision history. Place the insertion point just to the left of your Revision entry, and press the <ENTER> key. The insertion point appears on a new, blank line between Author's email: and Revision (number): .

LyX main window:

     Author's email: your-address@example.com
|
      Revision (number):  0.01
    

Select RevisionHistory from the drop-down list of styles.

Drop-down styles list:    RevisionHistory
    

Your fully wrapped Revision history looks like this.

LyX main window:

Revision history
      Revision (number):  0.01
      Revision date: today's date
      Reviser's initials: you
      Revision remark: A meaningful comment
    

You can add new revisions later, either above Revision (number), or below Revision remark. Be consistent though. Include Date, Initials and RevisionRemark. Then insert the Revision (number) wrapper at the top of the details.


3. lyxstyles used in newbieDoc

You select the lyx command, paragraph or environment from the drop-down list on the very left of the button bar.


3.1. Section

The heading 'Section' above begins a first level section. It is created by the lyx 'Section' command. The 'Section' command takes your typed text and puts it in an SGML container of <title></title> tags. It also creates first level <sect1></sect1> tags to contain the title.

NoteNote: check for validity.
 

The <sect1></sect1> tags must also contain at least one another container. You must add this manually using a LyX command (eg 'Subsection') or a Lyx environment/paragraph (eg 'Standard').

A 'section' command is usually followed by a Subsection command or by 'Standard' text. Here is the SGML generated by exporting from lyx to DocBook:

1 <sect1>
2   <title> First level section </title>
3   <para>
4     Text added using LyX's 'Standard' 
5     paragraph.
6   </para>
7 </sect1>
8    

3.2. Subsection

The subsection is the next level down.

1    <sect2>
2     <title>Subsection</title>
3    </sect2>
4    

3.3. Subsubsection, Paragraph and Subparagraph

ImportantParagraphs
 

Do not confuse this “Paragraph” (which is a heading) with “Standard” (which is a paragraph of text).

These lyx commands illustrate the hierarchy of article sections.


3.3.1. Subsubsection

3.3.1.1. Paragraph
3.3.1.1.1. Subparagraph

This is 'Standard' text within the fifth level section.

Here is the SGML generated from the previous 'Subsection'. It is slightly edited to make it easier to read:

1     <sect3>
2      <title>Subsubsection</title>
3      <sect4>
4       <title>Paragraph</title>
5       <sect5>
6        <title>Subparagraph.</title>
7         <para>
8           This is 'Standard' text within the fifth level heading.
9         </para>
10       </sect5>
11      </sect4>
12     </sect3>
13    </sect2>
14       

It is best to avoid using the 'Paragraph' and 'Subparagraph' commands.


3.4. Standard text (<para></para>)

Paragraphs are simple. You use lyx's 'Standard' paragraph. Pressing the <ENTER> key starts another one.

'Standard' follows on by default after certain lyx commands.

Here is the SGML code generated from the two paragraphs above:

1     <para> 
2       Paragraphs are simple. You use LyX's 'Standard'
3       paragraph. Pressing the <ENTER> key starts another
4       one.
5     </para>
6 
7     <para> 
8       'Standard' follows on by default after certain LyX commands. 
9     </para>
10    

3.5. Lists

3.5.1. Bulletted list

The 'Itemize' style produces a bulletted list.

Here is the resulting SGML:

1  <itemizedlist>
2 
3    <listitem>
4      <para>first list item</para>
5    </listitem>
6 
7    <listitem>
8      <para>second list item</para>
9    </listitem>
10 
11    <listitem>
12      <para>third list item</para>
13    </listitem>
14 
15   </itemizedlist>
16     

3.5.2. Numbered list

Do not type the numbers - they are added automatically.

  1. first list item

  2. second list item

  3. third list item

Here is the resulting SGML:

1    <orderedlist>
2 
3      <listitem>
4        <para>first list item</para>
5      </listitem>
6 
7      <listitem>
8        <para>second list item</para>
9      </listitem>
10 
11      <listitem>
12        <para>third list item</para>
13      </listitem>
14 
15    </orderedlist>
16     

3.5.3. A list of descriptions

Does not render very well with the current CSS style sheet.

The first word you type is highlighted as in a dictionary. The remaining words before the new line are not highlighted.

NoteNote: Item names with more the one word.
 

You can protect spaces within an item's name. Use Insert->Special Character->Protected Blank or hold down the CTRL and SHIFT keys while pressing the SPACE BAR.

Here is the resulting SGML:

1    <variablelist>
2 
3      <varlistentry>
4        <term>first</term>
5        <listitem>
6          <para>list item</para>
7        </listitem>
8      </varlistentry>
9 
10      <varlistentry>
11        <term>second</term>
12        <listitem>
13          <para>list item</para>
14        </listitem>
15      </varlistentry>
16 
17      <varlistentry>
18        <term>third&nbsp;with&nbsp;protected&nbsp;spaces</term>
19        <listitem>
20          <para>list item</para>
21        </listitem>
22      </varlistentry>
23 
24    </variablelist>
25     

3.6. Code, screen and xscreen


3.6.2. Screen

Screen is another environment for character data. You can use it for any text that appears on the screen - input or output. Screen is similar to code, but does not have line numbers.

if (x=y){
   $variable=1
} else {
   $variable=0
}
    

Here is the generated SGML code:

<screen>
     <![CDATA[if (x=y){
  ]]><![CDATA[   $variable=1
  ]]><![CDATA[} else {
  ]]><![CDATA[   $variable=0
  ]]><![CDATA[}
  ]]>
</screen>
    

3.8. Comments

3.8.1. SGML Comment

This comment appears in both the lyx document and the SGML document.

Drop-down styles list:    SGML

LyX main window:   
<!-- Text must be contained by "<", "!", "-", "-" and "-", "-", ">". The whole thing must be in the SGML paragraph style. -->
    

3.8.2. lyx Comment

These comments only appear in the lyx document.

Drop-down styles list:    Comment

LyX main window:    Comment:     Your meaningful comment
    

You may find lyx note a useful alternative.


3.8.3. lyxNote

NoteNote: Note style and lyx Note
 

These are not the same thing! This paragraph uses the 'Note' style from the Drop-down styles list. The Lyx Note is one of lyx's features. It is like a post-it note.

These comments only appear in the lyx document.

Menu bar:    Insert -> Note

LyX main window:  Your comment is in a bright yellow box. It can be revealed or hidden by a grey tab labelled “note”.
    


3.9. HTML metadata keywords

You can insert HTML <meta NAME="KEYWORD" CONTENT="keyword"> tags which are used by some search engines as evidence of relevance. You must make a separate entry for each keyword. They must be inserted at the head of the lyx document immediately before the abstract.

Drop-down styles list:    Keyword

LyX main window:    

     Keyword:    keyword-1
   

You must add a KeywordSet wrapper immediately above the first Keyword.

Drop-down styles list:    KeywordSet

LyX main window:  

Keyword set
     Keyword:    keyword-1
   

You can add more keywords to your keyword set:

Drop-down styles list:    KeywordSet

LyX main window:  

Keyword set
     Keyword:    keyword-1
     Keyword:    keyword-2
   

The SGML code looks like this.

1 <keywordset>
2   <keyword>
3     keyword-1
4   </keyword>
5   <keyword>
6     keyword-2
7   </keyword>
8 </keywordset>
9    

4. Inline elements

Inline elements apply to individual characters rather than to whole lyx environments. This is lyx's weakest area.


5. Tables

5.1. Inserting a table

Tables are straight-forward. Position the insertion point. Either click on the Insert Table button, or use the Insert drop-down menu:

Menu bar:    Insert -> Tabular material...

Insert table dialogue:    Rows -> (number) -> Columns -> (number) -> OK
   

The 'Insert Table' dialogue shows the graphical representation of a table (initially 5x5). Select the table's size in rows and columns. You can do this by typing in the numbers you want, clicking on '+' or '-', or by moving the bottom right-hand corner of the table widget with the mouse.

NoteNote: Header row.
 

lyx assumes that the first row contains column headings. lyx shows the header row separated from the rest of the table, but SGML export ignores this.

Here is a table with 3 rows and 2 columns:

Here is the SGML:

1 <para>
2   <informaltable>
3     <tgroup cols="2" colsep="1" rowsep="1"
4     <colspec colname="col0" align="center">
5     <colspec colname="col1" align="center">
6 
7       <tbody>
8 
9         <row>
10           <entry align="center" valign="top">
11             <para>Column heading   1</para>
12           </entry>
13           <entry align="center" valign="top">
14             <para>Column Heading 2</para>
15           </entry>
16         </row>
17 
18         <row>
19           <entry align="center" valign="top">
20             <para>2nd row, 1st column</para>
21           </entry>
22           <entry align="center" valign="top">
23             <para>2nd row, 2nd column</para>
24           </entry>
25         </row>
26 
27         <row>
28           <entry align="center" valign="top">
29             <para>3rd row, 1st column</para>
30           </entry>
31           <entry align="center" valign="top">
32             <para>3rd row, 2nd column</para>
33           </entry>
34         </row>
35 
36       </tbody>
37 
38     </tgroup>
39   </informaltable>
40 </para>   
41    

5.2. Links

5.2.1. External link (URL)

NoteNote: Names of external links.
 

It is a good idea to make the name of an external link identical to the URL. That way, printed copies of the final HTML page still contain the complete URL.

This link may enable you to jump to your localhost's index page: http://localhost.

The SGML code looks like this:

1    <para>
2 This link may enable you to jump to your 
3 localhost's index page:<ulink url="http://localhost">http://localhost</ulink>.
4    </para>
5     

This link will take you to the newbieDoc home page: http://newbiedoc.sourceforge.net/.

1    <para>
2 This link will take you to the newbieDoc home page: 
3 <ulink url="http://newbiedoc.sourceforge.net/">
4 http://newbiedoc.sourceforge.net/</ulink>.
5    </para>
6     

5.2.3. Internal link (cross reference or xref)

DocBook no longer supports xref to ANCHOR. However, it does support a link using the “ID” attribute.

The value of attribute "ID" and "LINKEND" attributes must be a single token. This means that you can use alphanumeric characters (letters and numbers) and the hyphen (-). Here are a couple of examples. First the SGML generated by lyx for including IDs in this 'Appendix' and its first 'Section':

1 <appendix id="Appendix-Examples-of-LyX-styles">
2   <title>
3     Examples of LyX styles used in newbieDoc
4   </title>
5 
6   <sect1 id="Golf-links">
7     <title>
8       Links
9    </title>
10     

Now the LINKENDs:

The big, fat dog ran around the Section 5.2 all by itself.

1    <para>
2      The big, fat dog ran around the <xref linkend="Golf-links">
3      all by itself.
4    </para>
5     

The lazy fox went to Appendix B instead.

1    <para>
2      The lazy fox went to 
3      <xref linkend="app-analysis-of-lyx-styles"> instead.
4    </para>
5     

6. ERT (Evil Red Text)

lyx is very powerful and flexible in its use of environments. Unfortunately, lyx is rather more limited in the way it handles character styles. The emphasis style adds <emphasis></emphasis> tags to the emphasise text when you export it to DocBook. For other inline elements you must embed the tags directly into your document. Use the TEX button (with a red TEX icon).


6.5. Other SGML styles

At the moment you must use Evil Red Text (ERT) for callouts, citations, graphics, etc. For example, here is the ERT to insert a graphic. (See NewbieDoc Docbook Guide).

<mediaobject>
  <imageobject>
    <imagedata fileref="images/newbieDocLogotype.ps" format="ps">
  </imageobject>
  <imageobject>
    <imagedata fileref="images/newbieDocLogotype.eps" format="eps">
  </imageobject>
  <imageobject>
    <imagedata fileref="../images/newbieDocLogotype.gif" format="gif">
  </imageobject>
  <textobject>
    <phrase>Newbiedoc: Docs for & by Debian newbies.</phrase>
  </textobject>
  <caption>
    <para>Newbiedoc: Docs for & by Debian newbies.</para>
  </caption>
</mediaobject>
   

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.


B. Appendix: Analysis of lyx styles and layout files

Style

File

LatexType

LatexName

LatexParam

Other

 

newbiedoc-docbook.layout

 

 

 

Input nd_stdclass.inc, MaxCounter Counter_Section, NoStyle Part, NoStyle Chapter

 

nd_stdclass.inc

 

 

 

OutputType docbook

 

nd_stdclass.inc

 

 

 

Default: Columns, Sides, SecNumDepth, TocDepth, DefaultStyle. DefaultFont

 

nd_stdclass.inc

 

 

 

Import .inc files

 

nd_stdcounters.inc

 

 

 

Counters for Section etc

SGML

nd_stdlayouts.inc

Paragraph

"!-- --"

NewLine 0

Screen

nd_stdlayouts.inc

Environment

screen

CDATA

PassThru 1, FreeSpacing 1

XScreen

nd_stdlayouts.inc

Environment

synopsis

CDATA

PassThru 1, FreeSpacing 1

Standard

nd_stdclass.inc

Paragraph

para

 

LabelType No_Label

Itemize

nd_stdlists.inc

Item_Environment

itemizedlist

 

 

Enumerate

nd_stdlists.inc

Item_Environment

orderedlist

 

 

Description

nd_stdlists.inc

Item_Environment

variablelist

 

 

Part

nd_stdsections.inc

Command

part

"0|"

 

Chapter

nd_stdsections.inc

Command

chapter

"1|"

 

Appendix

nd_stdsections.inc

Command

appendix

"1|"

 

Section

nd_stdsections.inc

Command

sect1

“2|”

 

Subsection

nd_stdsections.inc

Command

sect2

“3|”

 

Subsubsection

nd_stdsections.inc

Command

sect3

“4|”

 

Paragraph

nd_stdsections.inc

Command

sect4

“5|”

 

Subparagraph

nd_stdsections.inc

Command

sect5

“6|”

 

Abstract

nd_stdstruct.inc

Command

abstract

"3|para"

 

PageHeader

nd_stdtitle.inc

Paragraph

title

InTitle 1

Title

nd_stdtitle.inc

Command

articleinfo

“2|”

Labelstring “Title”

Date

nd_stdtitle.inc

Paragraph

date

Labelstring “Revision date”

Header

nd_stdtitle.inc

Paragraph

title

“1|”

Labelstring “Header”

Firstname

nd_stdtitle.inc

Command

author

“4| firstname”

InTitle 1

Surname

nd_stdtitle.inc

Paragraph

surname

 

InTitle 1

Affiliation

nd_stdtitle.inc

Command

affiliation

“5|!-- --”

Labelstring “Affiliation, address”

Email

nd_stdtitle.inc

Command

address

“6|email”

Labelstring “Author's email”

Revision

nd_stdtitle.inc

Command

revision

"4|revnumber"

 

Date

nd_stdtitle.inc

Paragraph

date

 

 

Initials

nd_stdtitle.inc

Paragraph

authorinitials

 

InTitle 1

RevisionRemark

nd_stdtitle.inc

Paragraph

revremark

 

InTitle 1

RevisionHistory

nd_stdtitle.inc

Command

revhistory

"3|!-- --"

 

TipTitle

nd-admonitions.inc

Environment

tip

title

LabelString “Tip Title: “

Tip

nd-admonitions.inc

Environment

tip

para

LabelString "Tip: "

NoteTitle

nd-admonitions.inc

Environment

note

title

LabelString "Note Title: "

Note

nd-admonitions.inc

Environment

note

para

LabelString "Note: "

ImportantTitle

nd-admonitions.inc

Environment

important

title

LabelString "Important Title: “

Important

nd-admonitions.inc

Environment

important

para

LabelString "Important: “

CautionTitle

nd-admonitions.inc

Environment

caution

title

LabelString "Caution Title: “

Caution

nd-admonitions.inc

Environment

caution

para

LabelString "Caution: “

WarningTitle

nd-admonitions.inc

Environment

warning

title

LabelString "Warning Title: “

Warning

nd-admonitions.inc

Environment

warning

para

LabelString "Warning: “

Code

nd_lyxmacros.inc

Environment

programlisting

CDATA

PassThru 1

Comment

nd_lyxmacros.inc

Paragraph

remark

 

 

Keyword

nd_extra.inc

Paragraph

keyword

 

 

KeywordSet

nd_extra.inc

Command

keywordset

"3|!-- --"