Chapter 5.  Conventions
Prev  Part I. Introduction  Next
pyswarm Documentation (http://pyswarm.sourceforge.net/)

Chapter 5.  Conventions

This book uses the following typographical conventions to mark certain portions of text: new terms and other important passages are emphasized as well as foreign phrases . Directories and files (including Python packages and modules), classes, attributes and parameters, methods, and values (e.g. numbers, alpha-numeric strings, literals) are usually shown in a monospace font. This applies also to database-specific identifiers such as tables and columns.

Everything that represents input or output of the computer, in particular commands, program code, and screen output, is shown in a monospaced font (see below). Within such passages, italics ( example ) indicate placeholders; you must insert an actual value instead of the placeholder. On occasion, parts of program code are emphasized in bold face or bold italic face, if they have been added or changed since the preceding example.

In some cases information are provided regarding graphical user-interfaces. Conventions here are as following: GUI label (just any label, such as a text in the GUI) or GUI button . Sub-sequent menu choices are provided as following: GUI menu -> Sub-menu -> Menu item

You will also find procedures which provide steps that need be applied sub-sequently (and if explicitely stated: optionally or alternativelly) in order to achieve a certain action:

  1. First step in the procedure.

    1. Sub-step of first step.

    2. Another sub-step.

  2. Second step

Procedure 5.1. Example of a Procedure

Example 5.1.  Example of a Command Synopsis

cmd {{ arg1 arg2... [opt1 [= value1 ]] [opt2= value2 ] } | {otherchoice}}

The following conventions are used in the synopsis of a command: brackets ([ and ]) indicate optional parts. Braces ({ and }) and vertical lines (|) indicate that you must choose one alternative. Dots (...) mean that the preceding element can be repeated.

The given example requires to provide either the otherchoice or arg1 along with the other parts.

arg1

If arg1 is provided, also arg2 is needed.

arg2

At least one arg2 is required if arg1 is given.

option

As far as arg1 and arg2 are provided, opt1 and opt2 are the optional part and can be provided or not. value1 is optional, so you can provide the option opt1 with this value or not. Providing the second option opt2 requires providing of value2 , too.

otherchoice

Either provide otherchoice alone or you need to provide the first part (arg1, arg2). --help would be a typical example. Usually you can't combine that with other arguments and options in a command, at least not in a senseful manner.

Example 5.2.  Example of Program Listing With No Call-Outs 

               filename.py:

                def sayHello():
                print 'Hello World!'

                sayHello()

Example 5.3.  Example of Program Listing With Call-Outs 

# PetStore/Internet/Shop/AdM/ZipAddress/printLetter.py

                    # Here we go with our custom business logic
                    strText = ''
                    if withSubject:                        
                     (1)
                  
                    # Return address information including
                    # attribute subject
                    strText += self.getSubject(oOp)
                    strText += '\n'

                    strText += self.getZipCode(oOp) + ' '  
                     (2)
                  
                    strText += self.getLocationName(oOp)   
                     (2)
                  

                    return strText
1

Information added to explain single call-out

2

Information added to explain range of call-outs

Example 5.4. Example of Screen 

                06-11-27 11:50:53 SDK.PARS   DEBUG  XMI element has "type" attribute
                with value: LogicComponent
                06-11-27 11:50:53 SDK.PARS   DEBUG  Initializing new parse node of ty
                pe "LogicComponent"
                06-11-27 11:50:53 SDK.PARS   DEBUG  XMI element has "name" attribute
                with value: AdM
                06-11-27 11:50:53 SDK.PARS   DEBUG  XMI element has "xmi:id" attribut
                e with value: _10_5_1_b8602f5_114
                4658916196_442583_222
                06-11-27 11:50:53 SDK.PARS   DEBUG  XMI element has "xmi:type" attrib
                ute with value: uml:Component
                06-11-27 11:50:53 SDK.PARS   DEBUG  XMI element has "visibility" attr
                ibute with value: public
                06-11-27 11:50:53 SDK.PARS   DEBUG  registered pyswarm.component.lo
                gic. Name:AdM / XMI ID: _10_5_1_b
                8602f5_1144658916196_442583_222
                06-11-27 11:50:53 SDK.PARS   DEBUG  XMI element has "type" attribute
                with value: Entity
                06-11-27 11:50:53 SDK.PARS   DEBUG  Initializing new parse node of ty
                pe "Entity"
[Caution] Caution

Ignoring a caution like this one will definitely harm a system, including loss of data, or it is very likely to happen.

[Warning] Warning

Ignoring a warning like this one may cause severe problems to a system, including loss of data.

[Important] Important

Important notices like this one should get your attention. They usually point you to information which are necessary to know.

[Tip] Tip

Tips like this one may have useful information that may save your time.

[Note] Note

Notes like this one may provide additional information to the context in which it appears.

Example 5.5. Example of User Input on Win32

D:\pyswarm\SDK\> C:\applicationdir\app.exe

Example 5.6. Example of User Input on Unix as Normal User

$ /usr/local/bin/app pyswarm-generate.py --help

Example 5.7. Example of User Input on Unix as Super User

# /usr/local/bin/app pyswarm-generate.py --help

[Note] Note

If execution of a command requires administration (super user) privileges this is indicated by a # prompt.

An administrator is generally a person who is in charge of installing and running applications or components. A user or developer could be anyone who is using, or wants to use, any part of pyswarm to create an pyswarm-based application. End-users are using pyswarm-based applications created by users/developers. These terms should not be interpreted too narrowly.

This document was created using the >e-novative> DocBook Environment (eDE)
Prev  Up  Next
Chapter 4.  A Brief History of pyswarm   Home  Chapter 6.  Community