This page gives information for editors of material for the TDR.

The editing tool which will be used for the TDR is Adobe FrameMaker 6. The document will be organised in a FrameMaker book containing chapter files and if required sub-chapter files.

Text: the editorial board will only accept FrameMaker files using the official template. Alternatively and only exceptionally it will accept plain ASCII text files.

Figures: Although FrameMaker allows for import of different graphics file formats, the editorial board insists that all figures be submitted as Encapsulated PostScript (EPS) files with an .eps extension. If you have valid reasons to submit figures in a different format then please contact Marc Dobson. See the later section for more details.

FrameMaker is supported at CERN by the IT DocSys and SDT groups. The template which will be used is based on a TDR template developed by the IT DocSys group.

Instructions can be found on the DocSys web page, on how to setup and run FrameMaker at CERN. If editors want to install FrameMaker on their non CERN laptops then please contact Marc Dobson.

FrameMaker comes with an extensive online Help facility. The printed FrameMaker documentation is not included with the CERN site license, but can be ordered separately. Other site licence arrangements often allow separate purchase of licences, CD-ROMs and manuals. The CERN UCO bookshop also stock a few books on FrameMaker.

FrameMaker template

The template which will be used is based on a TDR template developed by the IT DocSys group. On that web page there are links for an online and a PDF format manual for the template. This is compulsory reading for editors.

From a pedestrian's point of view, a FrameMaker template is an 'empty' FrameMaker file that contains a predefined page layout and a number of paragraph and character formatting tools. It is thus similar to a Word template and a remote relative of a LaTeX style file; the principal difference to LaTeX is that you type your text directly into the template. It is important to realize that the style information is 'local' to each FrameMaker file, and thus cannot be easily maintained in a centralized way.

Cross-platform compatibility

FrameMaker binary files can be exchanged between all supported platforms.

Although FrameMaker allows for import of different graphics file formats, the editors insist that all figures be submitted as Encapsulated PostScript (EPS) files with an .eps extension, in order to ensure a consistently high output quality and to allow for editing of figures if necessary (e.g. to change fonts or font sizes). An exception to this rule which is being considered is the use of 'mif' files which are directly understood by Framemaker and allow editing. If you have valid reasons to submit figures in a different format then please contact Marc Dobson (good quality JPEG or GIF would be accepted for pictures).

Comment on importing graphics

FrameMaker provides two options for importing graphics into text files: (a) import by reference, or (b) copy into document. (Importing by reference is similar to importing EPS files into LaTeX files via the epsfig macro.) Note: We will only use the import-by-reference option, in order to keep file sizes manageable, and to allow for automatic updating of figures without updating the FrameMaker file. The important consequence is that all figures must be submitted to the editors separately, one figure (which could contain several closely-related parts) per EPS file.

Dos & Don'ts

1. Figures should be either half a page wide or full page wide. They should not be scaled. From PAW and using the KUMAC below, there is one parameter to change to switch between these sizes.
    
2. Make sure lettering is readable: capital letters should appear at least 2 mm high in the final printed output.
    
3. Figures should not have a bordering rectangle.
    
4. Avoid headers, titles and lengthy text that belongs in the figure caption.
    
5. Use fonts for lettering that are consistent with the main text, where we use only Helvetica (sans-serif) and Palatino (serif):
   • Helvetica is the preferred font for lettering figures.
   • If serif fonts cannot be avoided, respect a basic rule of good typography: different serif fonts should not be mixed in the same document, i.e. use Palatino (avoid Times, Bookman, ...).
   
    
6. Avoid italics, boldface and other emphasis, unless there is a good reason to do so.
    
7. For PAW figures, L. Chevalier has prepared a KUMAC file that respects the rules, and that should be used by everybody to ensure consistent appearance.
    
8. Line-art figures should be submitted in black & white only since coloured lines usually do not print well in b/w output. Coloured areas (shadings) are permitted when they translate well into shades of grey. Authors should check to ensure that all figures print well in black & white.
    
9. If at all possible, figures should have a unique ID in small letters somewhere, preferably the lower right-hand corner. The form is XYZnnVmm, where XYZ are the initials of the person responsible for the figure, nn is a unique number chosen by that person, and mm is the version number. The filename should then start with the ID, e.g. EFE04V02_TrigStuff.eps.

Checking EPS files

Some EPS figures prevent the PostScript file of the completed chapter from being viewed with Ghostview. Authors should produce a PostScript file containing their figures and check that all of them can be viewed in Ghostview prior to submission. This is usually a good check that all EPS files are free from PostScript problems.

Colour figures are forbidden!

The use of colour figures is strongly discouraged for various reasons. If you feel that you absolutely need a colour figure then please ask Marc Dobson.

The TDR master directory

The different versions of the TDR will be located on a dedicated AFS area, namely /afs/cern.ch/atlas/project/tdr/tdaq/hltdaqdcs/.

The latest version of the TDR will be kept in the latest directory.

The structure of this directory is hierarchical and reflects the structure of the TDR. It is organised into directories for the different parts of the document. Each part directory contains the part file and directories for each of the chapters in that part. Each chapter directory contains the chapter Framemaker files and an imported directory where all figures for this chapter should be placed. The frontmatter (cover etc...) and the automatically generated files (TOC, LOF, etc...) are also located in sub-directories. The Framemaker book itself is located in the root directory of the structure. For illustration the structure is shown below.

outline
|-- AutoFiles
|   |-- TDR_LOF.fm
|   |-- TDR_LOT.fm
|   `-- TDR_TOC.fm
|-- Colophon.fm
|-- FrontMatter
|   |-- FrontMatter.fm
|   `-- imported
|-- PDF
|   `-- TDR.pdf
|-- Part1GlobalView
|   |-- ChapArchitecture
|   |   |-- Architecture.fm
|   |   `-- imported
|   |-- ChapEventSelect
|   |   |-- EventSelection.fm
|   |   `-- imported
|   |-- ChapFaultError
|   |   |-- FaultError.fm
|   |   `-- imported
|   |-- ChapMonitoring
|   |   |-- Monitoring.fm
|   |   `-- imported
|   |-- ChapOverview
|   |   |-- Overview.fm
|   |   `-- imported
|   |-- ChapParameters
|   |   |-- Parameters.fm
|   |   `-- imported
|   |-- ChapSystemOps
|   |   |-- SystemOps.fm
|   |   `-- imported
|   `-- Part1GlobalView.fm
|-- Part2SysComponents
|   |-- ChapCtrlandSupervision
|   |   |-- CtrlandSupervision.fm
|   |   `-- imported
|   |-- ChapDCS
|   |   |-- DCS.fm
|   |   `-- imported
|   |-- ChapDFComponents
|   |   |-- DFComponents.fm
|   |   `-- imported
|   |-- ChapHLTComponents
|   |   |-- HLTComponents.fm
|   |   `-- imported
|   |-- ChapOnlSWComponents
|   |   |-- OnlSWComponents.fm
|   |   `-- imported
|   `-- Part2SysComponents.fm
|-- Part3SysPerf
|   |-- ChapPhysHLTPerf
|   |   |-- PhysHLTPerf.fm
|   |   `-- imported
|   |-- ChapSysPerf
|   |   |-- SysPerf.fm
|   |   `-- imported
|   `-- Part3SysPerf.fm
|-- Part4OrgPlan
|   |-- ChapCosting
|   |   |-- Costing.fm
|   |   `-- imported
|   |-- ChapOrgRes
|   |   |-- OrgRes.fm
|   |   `-- imported
|   |-- ChapQAandSDP
|   |   |-- QAandSDP.fm
|   |   `-- imported
|   |-- ChapWorkplan
|   |   |-- Workplan.fm
|   |   `-- imported
|   `-- Part4OrgPlan.fm
|-- TDR.bk
`-- templates
    |-- Appendix.fm
    |-- Chapter.fm
    |-- Colophon.fm
    |-- ColourFigures.fm
    |-- FrontMatter.fm
    `-- Part.fm
            

Note that the template files, edited for our TDR are also included in the structure in the templates directory. You should not need these.

The directory submit is where the editors should upload the updated chapter files when requested to do so.
 

The working environment

You should be using Framemaker 6 to edit the TDR files.

You should copy or download the latest directory to the machine where you wish to edit.

You should have at the very least the AutoFiles directory, the FrontMatter directory, the Colophon.doc file, the TDR.bk file, and any chapter directories you are allowed to work with. Ideally you should have all the main book file and all the .doc files with all the various ddirectories and subdirectories so that you get unrestricted access to cross-referencing.

Important: You should NEVER rename any files in your local copy.
 

Editing your chapters

Always open the TDR.bk book file, then open the relevant chapter file from the book window. Use the corresponding chapter/imported directory to store the figures for your chapter.

Be sure to follow exactly the instructions in the User Manual for the template, and especially the section on the things that are not allowed. Also be sure to follow the recommendations on this page and report problems to Marc Dobson.

Once again remember to import figures by reference only.

If you are a sub-editor and need to combine files from different authors, only use the Import File... command to ensure consistent formatting. In contrast to importing figures, text files including tables must be imported using the Copy into text option, not by reference.

When working on a copy of a file, Framemaker might warn you about missing files (most likely figures imported by reference). Activating Ignore All Missing Files will then allow you to edit the file.
 

Predefined symbols

A set of predefined symbols, expressions and equations (similar to those used in the Technical Proposal and LaTeX) is available in all files used in the TDR. These symbols (shortcuts) are documented in the User Manual for the TDR template. Please use these symbols whenever possible in order to contribute to a consistent appearance of the TDR, and tell us about symbols that you find missing and would like to see implemented.

Cross-references to other chapters

The reason for working with the complete TDR directory, and not only with your chapter, is that you need the others to implement automatic cross-references to other chapters. How to do this is explained in the template User Manual; you have to open the chapter file to which you want to make a reference from the book window. Of course, for the time being, you can only make references to headings, figures etc. of other chapters to the extent where they exist already. For the time being, just mark cross-references that you cannot implement yet in a convenient way (e.g. a question mark). There are no restrictions as to cross-referencing inside your own chapter.

Updating to new templates

The templates might still evolve. However, all work you do now will not be lost. Instructions for upgrading existing files to new templates can be found in the template User Manual.

What to do, and NOT to do

• Above all compose and write your contribution, bearing in mind that it should be complete, concise, accurate and easily comprehensible.
   
• Do not try to 'improve' the appearance of things beyond what the template allows you to do. If you are unhappy with the appearance of some part of your contribution then please discuss it will the editor.
   
• Do not hesitate to ask for help on how to do certain things.
   
• The usage of word processors or raw ASCII text is not recommended as later updates will involve a lot of work to merge changed.
   
• DO NOT ALTER the FrameMaker Template! This will lead to unexpected behaviour.
   
• DO NOT ALTER paragraph formats in the template.
   
• DO NOT USE FONTS other than those defined in the template. These are defined for maximum cross platform independence.
   
• Bear in mind that if you create new files (do you really need to?) the names should be valid on UNIX and Windows (not more than one dot; only lowercase; suffix should be no longer than 3 characters).
   
• Learn how to do 'unbreakable space' and 'unbreakable hyphen'.
   
• Use the pre-defined variables as much as possible to allow for a unique appearance throughout the document.
   
• Take the time to run your contributions through the spell checker before handing it in.
   
• DO NOT EDIT the global FrameMaker book file.

Spellchecking: Use British, not American, spelling and spellchecking. Note that the FrameMaker spellchecker allows a choice between the two, therefore set your preferences correctly.

Words ending in 'ise' vs. 'ize': Although it is commonly believed that this is a British vs. American spelling issue, at least one eminent British publisher uses 'ize'. We suggest that for mid-Atlantic harmony people use 'ize' ('polarize, polarization, ...).

Capitalization: Avoid unnecessary capitalization in both section headings and names (barrel toroid, not Barrel Toroid, argon, not Argon, etc.). However, ATLAS must always be fully capitalized!

Numbers: Numbers smaller than 10 are always spelled out ('three or four layers, this is the question'); bigger numbers are given as such. A number at the beginning of a sentence is always spelled out.

Hyphens, n-dashes, and m-dashes: These special characters are distinct from hyphens, the n-dash being slightly larger and the m-dash larger still. Hyphens go between words, e.g dim-witted proof reader (but also front-end, end-cap, level-1). N-dashes go between items in a series, such as numbers e.g 1999-2001 or pp. 21-32, and also where two items are paired or balanced, e.g. East-West conflict (but also 20­30 million Dollars, proton­proton). M-dashes frame interpolated phrases in a sentence, generally in pairs, e.g.: Our editors--both the new one and the old one--are very tired of fixing these dashes.
(NB: These dashes do NOT reproduce properly on web pages, including this one)

Multiplication: Use the proper 'cross' from the symbol font, not an ordinary x.

Mathematical and physical symbols: Remember that our FrameMaker templates provide a large number of variables for predefined symbols. Use them; they will save a lot of typesetting effort and at the same time ensure consistency!

Physical quantities: Connect number and unit by a non-breaking space to avoid breaking them across a line end. The keyboard convention for non-breaking spaces is operating-system dependent, so we cannot give all recipes here.

Units: If you are not sure about the use of physical units, follow the example of the Technical Proposal. Most importantly, c = 1, i.e. mass, momentum and energy are all measured in GeV.

Quotes: Use 'single', not "double" quotes.

Cross-references: Complete 'internal' cross-referencing to (sub)sections, figures, tables, equations and bibliographic references inside your own chapter (section), using the FrameMaker Special:Cross-references... menu, is required. Please make an effort to implement 'external' cross-references to foreign chapters as much as possible.

Abbreviations: Use capital letters for all two and three-letter abbreviations of system elements (an obvious exception is RoI and there are probably others, so see the glossary for more information). This includes "DAQ". In other words, please do not use "daq", "Daq" etc. When referring to multiple entities, do not put an apostrophe: "The ROB's send their data..." is incorrect. "The ROBs send..." is the correct version.

Limit abbreviations: Avoid introducing abbreviations/definitions for items that are not used extensively. Example: "The subsystem supervising and error handling master, SSEHM, is responsible for...". Unless SSEHM is used repeatedly further down in the text, there is no need for it to appear.

Use of ATLAS: Try not to use the word ATLAS too much in the text. Here is an example of a redundant mention: "This chapter describes the ATLAS XYZ".

Colloquialisms: Avoid them. Examples: "buy" vs "procure"; "get" vs "acquire"; "whole" vs "entire" etc.

Passive voice: "At present we plan to buy a new switch every three years". Better: "It is envisaged that a new switch will be procured every three years." In the light if this try to avoid the use of "he/she" for refering to e.g. the user, the developer (see next note also).

He/she: When refering to e.g. a user, a developer, etc... do not use "he/she" but just "he". It will be assumed that the "he" refers to either a person (male or female). Also try to reduce the use of "he" for the situations given in the examples above and only use it where it is clear who is being talked about.

Please refer to the ATLAS TDAQ glossary for the appropriate spelling, and definition of abbreviations, and terms.