CERN | IPT Group | FrameMaker at CERN

[Project Name -> running header] [Document Name -> running header]

Chapter 1
Overview

This is the chapter template file of the for Software Documentation Layout Templates. The first level heading is tagged H1 , with lower level headings from H2 to H6 .

NOTE
The text in these pages is only sample material indicating the use of this template. To get rid of it all just do Edit / Selcet all in Flow , and then Edit / Cut .

This is the chapter template file of the for Software Documentation Layout Templates. The first level heading is tagged H1 , with lower level headings from H2 to H6 .

1.1 Body text

The basic text paragraph style to use is Body . Other paragraph styles are available also, as indicated by the following sequence of paragraphs.

A BodyComment paragraph is similar a basic paragraph but the text font is italic.

A BodyInset paragraph is simply a normal text paragraph that is indented both from the left and from the right.

An information of secondary importance can be formatted using the BodySmall style, which is similar to normal text paragraphs except that the text font size is smaller than normal body text.

Pieces of code, or text that requires a fixed font, can be tagged with the BodyVerbatim
 tag, as in the following excerpt:1 
        if (snd != null) {
            snd.play();
        }

1.2 Lists

Bulleted and numbered list paragraphs, as well as list continuation paragraphs, are available at 3 levels. Other lists, such as alphabetic, roman and dashed, are only available at the first level. The following sequence indicates the use of these paragraph formsts.

A normal paragraph of text to separate the 2 list blocks...

  1. Numbered list items use a pair of paragraph formats: the first of the sequence uses the LNumber1Fst tag.
  2. The second of the sequence, and any thereafter, uses the LNumber1Nth tag.
  3. Ofcourse, continuation paragraphs may also be inserted in numbered list items, using the LCont1 paragraph style.

  4. The third of the sequence; also uses the LNumber1Nth tag.

1.2.1 Bulleted lists

...bla, bla, bla... Ridebis, et licet rideas. Ego ille quem nosti apros et quidem pulcherrimos cepi. Ipse? inquis. Ipse; non tamen ut omnino ab inertia mea et quete discederem.

1.2.2 Numbered Lists

...bla, bla, bla... Ridebis, et licet rideas. Ego ille quem nosti apros et quidem pulcherrimos cepi. Ipse? inquis. Ipse; non tamen ut omnino ab inertia mea et quete discederem.

  1. LNumber1.1st . ...bla, bla, bla... Ridebis, et licet rideas. Ego ille quem nosti apros et quidem pulcherrimos cepi.
  2. LNumber1.Nth . ...bla, bla, bla... Ridebis, et licet rideas. Ego ille quem nosti apros et quidem pulcherrimos cepi.
  3. LNumber2.1st . ...bla, bla, bla... Ridebis, et licet rideas. Ego ille quem nosti apros et quidem pulcherrimos cepi.
      1. LNumber3.1st . ...bla, bla, bla... Ridebis, et licet rideas. Ego ille quem nosti apros et quidem pulcherrimos cepi.
      2. LNumber3.Nth . ...bla, bla, bla... Ridebis, et licet rideas. Ego ille quem nosti apros et quidem pulcherrimos cepi.
      3. LNumber3.Nth . ...bla, bla, bla... Ridebis, et licet rideas. Ego ille quem nosti apros et quidem pulcherrimos cepi.
  4. LNumber2.Nth . ...bla, bla, bla... Ridebis, et licet rideas. Ego ille quem nosti apros et quidem pulcherrimos cepi.
    1. LCont2 . ...bla, bla, bla... Ridebis, et licet rideas. Ego ille quem nosti apros et quidem pulcherrimos cepi.

      LContVerbatim2
       
      ...bla, bla, bla... Ridebis, et licet rideas. 
      ...bla, bla, bla... Ridebis, et licet rideas. 
  5. LNumber1.Nth . ...bla, bla, bla... Ridebis, et licet rideas. Ego ille quem nosti apros et quidem pulcherrimos cepi.

1.2.3 Dashed, alphabetic and roman lists

  1. Lalpha1.1st . ...bla, bla, bla... Ridebis, et licet rideas. Ego ille quem nosti apros et quidem pulcherrimos cepi.
  2. Lalpha1.Nth . ...bla, bla, bla... Ridebis, et licet rideas. Ego ille quem nosti apros et quidem pulcherrimos cepi.
  3. LDash1 . ...bla, bla, bla... Ridebis, et licet rideas. Ego ille quem nosti apros et quidem pulcherrimos cepi.
    • LDash2 . ...bla, bla, bla... Ridebis, et licet rideas. Ego ille quem nosti apros et quidem pulcherrimos cepi.
      • LDash3 . ...bla, bla, bla... Ridebis, et licet rideas. Ego ille quem nosti apros et quidem pulcherrimos cepi.
  4. Lroman1.1st . ...bla, bla, bla... Ridebis, et licet rideas. Ego ille quem nosti apros et quidem pulcherrimos cepi.
  5. Lroman1.Nth . ...bla, bla, bla... Ridebis, et licet rideas. Ego ille quem nosti apros et quidem pulcherrimos cepi.

1.3 Definitions and Acronyms

Information that has the form of term and description can be formatted using a term paragraph followed by a description paragraph. There are 2 term and 3 description formats, which may be combined together to get the required effect.

We can divide the different possible combinations by whether the description starts on a new line or not.

1.3.1 Descriptions that start on a new line

This is the case when the term is tagged with the Dfn1.1Term paragraph format.

...bla, bla, bla... Ridebis, et licet rideas. (Dfn1.1Term)
Proinde cum venabere, licebit, auctore me, ut panarium et lagunculam sic etiam pugillares feras. Vale. ( Dfn1.2Desc0Ind )
...bla, bla, bla... Ridebis, et licet rideas. (Dfn1.1Term)
Proinde cum venabere, licebit, auctore me, ut panarium et lagunculam sic etiam pugillares feras. Vale. ( Dfn1.2Desc )
...bla, bla, bla... Ridebis, et licet rideas. (Dfn1.1Term)
Proinde cum venabere, licebit, auctore me, ut panarium et lagunculam sic etiam pugillares feras. Vale. ( Dfn1.2Desc2Ind )

1.3.2 Descriptions that do not start on a new line

This is the case when the term is tagged with the Dfn1.1TermRIH (Run-In Head) paragraph format.

...bla, bla, bla... Ridebis, et licet rideas. (Dfn1.1TermRIH)
Proinde cum venabere, licebit, auctore me, ut panarium et lagunculam sic etiam pugillares feras. Vale. ( Dfn1.2Desc0Ind )
...bla, bla, bla... Ridebis, et licet rideas. (Dfn1.1TermRIH)
Proinde cum venabere, licebit, auctore me, ut panarium et lagunculam sic etiam pugillares feras. Vale. ( Dfn1.2Desc )
...bla, bla, bla... Ridebis, et licet rideas. (Dfn1.1TermRIH)
Proinde cum venabere, licebit, auctore me, ut panarium et lagunculam sic etiam pugillares feras. ( Dfn1.2Desc2Ind )

1.3.3 Acronyms

The definition of an acronym is formatted by using one of the above pairs of term-description paragraph formats, namely Dfn1.1TermRIH followed by Dfn1.2Desc , e.g.

CAD
Computer Aided Design
HEP
High Energy Physics
OOA/OOD
Object-Oriented Analysis, Object-Oriented Design.

When using acronyms in the text, you may improve the printed results by typing the acronym in lowercase and then tagging it wih the Acronym character tag. The following two examples show the results obtained using the Acronym chbaracter tag (a) and just using standard uppercase (b).

  1. ...by importing from cad systems which conform to the step standard...
  2. ...by importing from CAD systems which conform to the STEP standard...

The disadvantage of using the Acronym character tag is that conversion to HTML may not have the same effect.

1.4 Tables

Tables, like figures and code listings, are always anchored in an empty PlaceHolder paragraph.

 

Table 5 Proinde cum venabere, licebit, auctore me, ut panarium et lagunculam sic etiam pugillares feras. Experieris non Dianam magis montibus quam Minervam inerare. Vale.

TblCellHeading
Aligning on decimals
TblCellHeadingCentre

TblCellBody 2

paratag . TblCellBodyDecimal

TblCellBodyCentre

Ipse; non tamen ut omnino ab inertia mea et quete.

0.987654321

12.0023478

Ipse; non tamen ut omnino ab inertia mea et quete.

Ipse; non tamen ut omnino ab inertia mea et quete.

what.ever

hey.there 3

Ipse; non tamen ut omnino ab inertia mea et quete.

...bla, bla, bla... Ridebis, et licet rideas. Ego ille quem nosti apros et quidem pulcherrimos cepi. Ipse? inquis. Ipse; non tamen ut omnino ab inertia mea et quete discederem. . Ego ille quem nosti apros et quidem pulcherrimos cepi. Ipse? inquis. 4

1.5 Figures

1.5.1 Figures within the text

Figures are formatted by first creating a PlaceHolder paragraph and then inserting a table using the Fig table format. An anchored frame is then inserted into the upper cell of the table, to contain the graphics for the figure.

 

Figure 1 A long fig caption: ...bla, bla, bla... Ridebis, et licet rideas. Ego ille quem nosti apros et quidem pulcherrimos cepi. Ipse? inquis. Ipse; non tamen ut omnino ab inertia mea et quete discederem. Ad retia sedebam: erat in proximo non venabulum aut lancea, sed stilus et pugilares: meditabar

 

...bla, bla, bla... Ridebis, et licet rideas. Ego ille quem nosti apros et quidem pulcherrimos cepi. Ipse? inquis. Ipse; non tamen ut omnino ab inertia mea et quete discederem. . Ego ille quem nosti apros et quidem pulcherrimos cepi. Ipse? inquis.

1.5.2 Full page figures

A full page figure may be inserted by clicking in a text paragraph5 and inserting a table of type FigFullPage . In the single cell of this table an Anchored Frame (17 x 21.4 cm, Below Current Line, Centred and Cropped) is inserted. This frame forces the table, which is set to float, to occupy exactly the next full page.

Figure 2 The architecture and the conversion process of LIGHT-OO: individual modules extract from the documents the information needed by LIGHT, the LIGHT webmaster can configure the generation process. The generated Web can be made public via any Web Server.

 

...bla, bla, bla... Ridebis, et licet rideas. Ego ille quem nosti apros et quidem pulcherrimos cepi. Ipse? inquis. Ipse; non tamen ut omnino ab inertia mea et quete discederem. . Ego ille quem nosti apros et quidem pulcherrimos cepi. Ipse? inquis.

1.6 Code listings

Code listings are formatted by first creating a PlaceHolder paragraph and then inserting a table using the CodeListing table format. The code is then inserted into the single table cell, formatted as 1 paragraph per line. If you would like the lines to be numbered then use the CodeLine paragraph tags. Otherwise you can just use the CodeVerbatim style.

 

Listing 1 A code listing with each source line automatically numbered, using the CodeLine.1st and CodeLine.Nth paragraph formats.

1: public boolean action(Event evt, Object arg) {
2: if (snd != null) {
3: snd.play();
4: }
5: if (url != null) {
6: System.out.println("GOTO: " + url);
7: getAppletContext().showDocument(url);
8: }
9: return true;
10: }

...bla, bla, bla... Ridebis, et licet rideas. Ego ille quem nosti apros et quidem pulcherrimos cepi. Ipse? inquis. Ipse; non tamen ut omnino ab inertia mea et quete discederem. . Ego ille quem nosti apros et quidem pulcherrimos cepi. Ipse? inquis.

 

Listing 2 The same code listing using the CodeVerbatim paragraph style.

 public boolean action(Event evt, Object arg) { 
        if (snd != null) { 
            snd.play(); 
        } 
        if (url != null) { 
            System.out.println("GOTO: " + url); 
            getAppletContext().showDocument(url); 
        } 
        return true; 
    } 

Commands or tiny excerpts may be formatted using the Snippet table format, which does not require a caption. Again the table is encapsulated into a blank PlaceHolder paragraph.

 

uncompress archive.tar.Z 
tar xvf archive.tar 

...bla, bla, bla... Ridebis, et licet rideas. Ego ille quem nosti apros et quidem pulcherrimos cepi. Ipse? inquis. Ipse; non tamen ut omnino ab inertia mea et quete discederem. . Ego ille quem nosti apros et quidem pulcherrimos cepi. Ipse? inquis.

1.7 Equations

(1)

1.8 References

  1. Software Engineering Standards , C.Mazza, J.Fairclough, B.Melton, D. de Pablo, A.Scheffer, R.Stevens, Prentice Hall, ISBN 0-13-106568-8, 1994. These are the PSS-05 standards defined by ESA Board for Software Standardisation and Control, BSSC.
  2. Software Engineering Guides , C.Mazza, J.Fairclough, B.Melton, D. de Pablo, A.Scheffer, R.Stevens, M.Jones, G.Alvisi, Prentice Hall, ISBN 0-13-449281-1, 1996.
  3. Software Development Tools , CERN/IPT service.
    Documented on the WWW at: http://www.cern.ch/PTTOOL/

1.9 Utility paragraphs

A little side margin note, relevant to adjacent text.

There are a few special utility paragraphs provided for convenience. These are UtilClearRestOfPage , that forces anything that follows it to the top of next page, UtilSideSticky , that can be used as a little margin note to record a comment at a particluar point in the document such as the margin note next to this paragraph, and UtilTBD , that can be used in draft documents to record an issue that is still to be discussed or done, as is indicated below.

TBD Can other useful utility formats also be provided ?

...bla, bla, bla... Ridebis, et licet rideas. Ego ille quem nosti apros et quidem pulcherrimos cepi. Ipse? inquis. Ipse; non tamen ut omnino ab inertia mea et quete discederem. . Ego ille quem nosti apros et quidem pulcherrimos cepi. Ipse? inquis.


 Warning Icon
Warning!

...bla, bla, bla... Ridebis, et licet rideas. Ego ille quem nosti apros et quidem pulcherrimos cepi. Ipse? inquis. Ipse; non tamen ut omnino ab inertia mea et quete discederem. . Ego ille quem nosti apros et quidem pulcherrimos cepi. Ipse? inquis



...bla, bla, bla... Ridebis, et licet rideas. Ego ille quem nosti apros et quidem pulcherrimos cepi. Ipse? inquis. Ipse; non tamen ut omnino ab inertia mea et quete discederem. . Ego ille quem nosti apros et quidem pulcherrimos cepi. Ipse? inquis.


 Note Icon
Note!

...bla, bla, bla... Ridebis, et licet rideas. Ego ille quem nosti apros et quidem pulcherrimos cepi. Ipse? inquis. Ipse; non tamen ut omnino ab inertia mea et quete discederem. . Ego ille quem nosti apros et quidem pulcherrimos cepi. Ipse? inquis




1. Hard Return characters (forced line break) are useful in these cases. They can be inserted by holding down the Shift key and pressing Enter .

2. A table footnote

3. How's it going ?

4. some footnote text

5. In the case of full-page fugures you must not use empty PlaceHolder paragraphs.


[Document Date] - WebMaster

Copyright © CERN