Framemaker: Editor-Please-Read (example)

Framemaker has a wealth of features. So much so that it is quite easy to generate Framemaker files that use these in ways that even an experienced editor can miss, and put in a lot of needless and possibly counter-productive work. Discovering what has been done can take time, and undoing unwanted changes made in the mean time can be very time consuming. Accordingly any novel or clever tricks should be documented in a way that a new editor will not miss. One way of doing this is to include a file at the beginning of a Framemaker book. The file can be ‘Excluded’ from the book, so it will not print or disrupt the book numbering. Such a file has to be in .fm format, but can also be saved as plain text and included with the package handed off to the next editor.
This page provides an example file. Any particular EDITOR-PLEASE-READ file should reflect the particular document and sources it describes.

---

802-1Q-Editor-Please-Read
This book/directory/WinZip archive contains a complete set of sources for P802.1Q/D1.2 as of the conclusion of Standards Association Recirculation Ballot. The PDF of the balloted text is included, file 802-1Q-rev-d1-2.pdf. The book has been rebuilt, to check for errors, so the file dates (and the date at the top corner of each page in the header) may have changed. The source files for each of the Figures has been checked, and in some cases the way the figures are included updated (using svg rather than OLE) to address detailed rendering issues (clumping of characters) associated with changing versions of Framemaker. See detail below in this read me files. The content of the figures and text remains unchanged, but slight differences in pagination may be present.

This file has been included in the Framemaker book, to draw it to the attention of anyone maintaining this set of files, but it is Excluded in the book (i.e. does not feature in the printed book).

This file should be useful to the IEEE staff editor for pre-publication editing final. It is also intended to be useful to new editors of amendments and revisions. Please do not feel slighted if some information is basic Framemaker. Any questions don’t hesitate to contact me.

Mick Seaman, Editor P802.1Q
mickseaman@gmail.com

Framemaker version

The Framemaker files are in FrameMaker2020.

Framemaker filenames and locations

All the files in the book (apart from this one) have names beginning ’Q’ and only the first few characters are required to uniquely identify each file and its clause. This is important for future maintenance: when many files are open in Framemaker tabs they can still be uniquely identified, reducing the chance of editing or copying text from the wrong file, including when snippets need to be taken verbatim from other 802.1 standards or future amendments. These should be in files whose names begin with the amendment designation, e.g., a P802.1Qdt clause 5 change should be in file “dt05.fm” in the book “Qdt.book”.

All the Framemaker (.fm) files in the book are in the “802-1Q” directory (name possibly extended to indicate revision/draft information). The Figures files, YANG trees, YANG files, MIB files are in subdirectories. The zip (or tar) file of the 802-1Q directory includes those subdirectories and files.

Page layouts, paragraph and other formats

Framemaker files from prior editions and amendments contained the usual accumulation of all the page layouts and paragraph formats Imported by successive editors. These have been scrubbed and I would be grateful if they were not reintroduced, as it takes a very long time to get a clean set for future maintenance. The problems included unfindable (now hopefully found and removed) and erratically reported cross-reference errors and font uses.

The paragraph formats currently used are aligned (more or less, so far as the appearance of the final text is concerned) with current IEEE formats, and should not be changed without a lot of thought as any less than thorough updating may result in unwanted errors (numbering changes, cross-reference failures, unwanted repagination etc.). The prior revision of 802.1Q was not internally consistent with regard to some format aspects (e.g. list item spacing varying anywhere from 12 point inter-paragraph spacing to 0 point). Most if not all of this variation has been adjusted. Significant attention has been paid to pagination at some points in the draft, as a common source of errors or comments has been the movement of a related concept to a subsequent page. Placing related material in the reader’s view has been deemed more important than line spacing at a few points.

Draft numbers, dates, and headers and footer information

The project designation and draft number appears as ordinary text in just one place (with the possible exception of YANG and MIB files) in the document: in the upper right of Q-frontmatter.fm in a paragraph format of “Designation”. Other occurrences of the project and draft (e.g. in the header of most pages) are cross-references to this occurrence. If the draft number is to be updated, change it in just this one place and then ’Update Book’ to update the cross-references. Similarly the date of the draft appears on the next line of Q-frontmatter.fm. It can be set manually or can be set using a Framemaker variable, but either way all the rest of the date occurrences will be automatically updated to match on ’Update Book’.

Similarly other items in the header on the Master Page for each page are actually cross-references to “Draft Revision .. networks-” and “Bridges and Bridged Networks” on the first frontmatter page. The “Copyright (c) 2022 ..” footer on each Master Page is a cross-reference to the same information on the Master Page ’Right’ in the frontmatter file, so the copyright date need only be changed on one page when advancing the calendar year.

Master Pages

All of the documents (files) in the Framemaker book from Clause 2 (Q02.fm) onwards use a single Master Page ’Right’. No other Master Pages should be added to these files. Do *not* bulk import page layouts from other sources. If it is necessary to update these pages (other than as already automatically done by cross-referencing – see above), then update the Clause 2 Master Page, select all the following files in the book and Import>Formats..>Page Layouts from Clause 2. Clause 1 currently has additional Master Pages for approved and unapproved first pages (as these lack, by past convention, the header). The Table of Contents, List of Figures, and List of Tables files all use the same Master Page ’Right’ as Clause 2. The frontmatter file has a few additional variants, whose purpose should be clear.

PDF Bookmarks

In the past some PDF Bookmarks were added by the staff editor after PDF production because of oddities in the bookmark choice or the use of inconvenient paragraph formats. The set of files for this project should generate all the desired bookmarks, in the desired format, without the need for such post-processing.

The “Title page” bookmark is produced for the Title page by including a white text ‘Title page’ paragraph format (with text “Title Page”) on the first line of the Title page.

Similarly the PDF bookmarks for each Annex collect information from following visible ‘Annex Type’ and ‘Annex Title’ paragraphs by including white text cross-references in the ‘Annex’ paragraph. This also solves the issue of how to get the ’Annex’, ’Annex Type’ and ’Annex Title’ on a single line in the Table of Contents.

Figures

Drawing Tools

The figures either use Framemaker’s own embedded drawing tools (preferred for simple figures) or are in Visio .vsd files (there is one historic exception – see below). Visio has been used where Framemaker’s drawing tool does not or did not provide the required detail of alignment accuracy (it is particularly bad at aligning grouped objects, particularly those including text, and arrows made up to match UML conventions). No other drawing tools are to be used, because of the possible maintenance burden.

Maintaining Visio figures

The original Visio .vsd (not .vsdx) files must be retained and supplied with any amendment. Recent experience (Framemaker 2020 version updates) has shown that Framemaker’s figure rendering can change with Framemaker version and no future editor should be left with the task of extracting figures from .fm files and reconstructing them prior to inclusion in a different format.

Any future edits to Visio figures must be done on the Visio files followed by reimporting them to Framemaker. These source files must be kept up to date. Do not click on the figure inside Framemaker and edit in place, this has the annoying tendency to place the figures ‘off grid’ as well as introducing differences between the source files and the final document. Failure to observe this rule has already led to the necessity to run an entire corrigendum project – on another standard.

Visio file locations and names

The Visio figures are in .vsd files named by clause, prefixed by “802-1Q-“, e.g., “802-1Q-06-Figures.vsd” for figures in Clause 6 and “802-1Q-C-Figures.vsd” for figures in Annex C. Some of the clauses have more than one .vsd file, e.g., “802-1Q-25-Figure-1.vsd” just contains Figure 25-1, while “802-1Q-25-Figure-4-10.vsd” contains Figure 25-1 through Figure 25-10.
Each Figure in a Visio file is on its own page, which is named (or at least has a name prefix) of “Fig ” followed by the figure number, e.g., “Fig 25-1”.
When a Figure in the numbered figure range indicated by the filename is actually drawn using Framemaker’s own tools, the Visio file contains a page named by the Figure number with text on the page stating that. If there is no .vsd file for a given clause then no Visio figures have been included in that clause.

Visio figure sizes and other parameters

The correct rendering of Visio figures is dependent on the units and the scaling of figures. The rendering process used to display a figure on the screen is not the same as that used to incorporate the figure in a PDF. Text and objects can be moved, font sizes changed, and text wrapped if inappropriate choices are made.

Figures are to be drawn using a page size of 6 inches x 9 inches (in Visio 2007 File>Page Setup>Page Size>Custom size: 6 in. x 9 in, File>Page Setup>Drawing Scale : No scale (1:1), File>Page Setup>Page Properties>Meaurement units: inches. This is the total page area available on an IEEE Standard page. Use of these settings avoids scaling fonts and consequent rendering issues. Do not use centimeters or millimeters, these can result in odd font sizes (e.g. 8.02 points, which then render incorrectly). A scale of 25.4 millimeters to 2.54 millimeters does not behave as a 10:1 inch scale. Using a Ruler and Grid set to Fine (Tools>Ruler & Grid) with a magnification (View>Zoom) of 200% is generally convenient, with Tools>Snap&Glue set to Snap to: Grid and everything else (or most everything else) off. The displayed Grid is then 1/8 inch, which is 9 pt. In the Framemaker file set Display Units and Font Units to “Point” and Grid Spacing to 3.0 pt (View>Options). The combination of these settings allows the accurate placement of lines/boxes/objects in the Visio diagram on the Framemaker together with any Framemaker text boxes that are wanted for cross-reference purposes.

At present Framemaker has a nasty, and random, habit of losing lines near the edges of a figure (for both cut-and-paste inclusion and SVG import). To guard against this place a 1/4″ square with white fill but no line at the top left and bottom right of the figure, and avoid using the right-hand and left-hand 1/8″ (the grid dimension) for the drawing.

Importing Visio figures by cut and paste

The Visio figures in this draft are included by using the cut-and-paste method, or by importing each figure as an svg file (described further below).

To cut-and-paste a figure, first insert an Anchored Frame in the Framemaker file. Generally this should be 432 pt wide (6 inches), by 426 pt can also be useful to make the frame distinct from the Framemaker page. This anchored frame will include the figure and (in a text box) the Figure Title, and any other text boxes that need to move along exactly with the figure. Select the drawing page in Visio (only one figure per page) and Ctrl-A (to select all on the page) and Ctrl-C (copy) from each Visio page. Select the Anchored Frame in Framemaker and Ctrl-V to paste in the figure. Do *not* use Visio’s “Copy Drawing” option – if you have more than one page in the Visio file this will copy all the pages and you will end up pasting them all into Framemaker (although this will not be apparent, apart from file size/responsiveness issues).

Once the Figure has been added to Framemaker in this way, it can be selected and Object Properties used to tweak its position. Using a multiple of 3 pt for distance from the top and from the left of the frame will keep it on grid.

The text in the included figure is searchable using the normal Acrobat searches of the PDF. This is very important for the some figures.

Importing a Visio figure as an SVG file

The quality of cut-and-paste Visio rendering has degraded over Framemaker releases, and in particular the positioning of characters on longer lines can exhibit bunching and overlap. To save a Visio figure as SVG, select the page in the Visio file and then Ctrl-A to select the drawing on the page. This is important: saving as SVG without selecting in this way saves more whitespace around the figure (at a minimum) and makes it harder to position the Figure in Framemaker. Then use Save As to save the figure as .svg. In Visio 2007 this is all that is required, in Visio 2019 there is an option to include Visio data in the saved svg and this needs to be selected to get the right result (the actual format of the saved “svg” file is anybody’s guess).

The saved svg file can then be imported into Framemaker. Select the Anchored Frame that will include the figures and File>Import>File. The figure can be imported by reference or by copy. Confusingly the result Object Properties will show both as copied into document. The advantage of the strict copy is that the Framemaker file now has no external dependencies. The advantage of he reference is that the figure will auto-update (sometimes some modest prompt, like clicking on the page is required) if the svg file is updated. The Object Properties can be used to adjust the position of the figure. Place it on the logical 3 point grid and any update will keep that positioning.

The disadvantage of svg inclusion is that the rendering can exhibit more oddities. The few figures still on a centimeter grid change font size and have not been svg included. Oddities have also been seen for object grouped in Visio – they can spring out of the group and land somewhere completely different in the PDF. Ungrouping in the Visio source has always fixed the latter issue.

Figure cross-references

Cross-references to each figure (including in the content’s list of figures) are to a paragraph of type ‘Figure’ that is in a text frame within and at the top of the anchored frame that includes the figure. This means that clicking on a cross-reference to the figure actually shows the figure on the screen, rather than showing the figure title at the top of the screen with the figure out of sight.

This improvement in figure cross-referencing has proved useful to users/reviewers. In particular it allows a one-click ‘Previous View’ return to the source of the cross-reference. Each ‘Figure’ paragraph uses White text (so it doesn’t show up). ‘Figure’ paragraphs that have been worked on recently contains a cross-reference to the corresponding ‘Figure Title’ (in the same anchored frame). There should be no need to change the cross-reference, even if the text of the Figure Title is edited. In older figures the figure title has been simply fixed in both paragraph types.

MIBs

MIB text and attached MIB files

The MIB modules in the body of the standard include clickable cross-references to the text in other clauses. Each of the MIBs is also attached to the standard as plain text file, as well as being available for download from the 802.1 website. The MIB text in the standard is (as per IEEE rules for the standard) the definitive standard. The source text for each MIB is a separate .fm, and the plain text attached files are extracted from that .fm file as follows.
The text at the front of the MIB .file, comprising the clause header (e.g. 17.7 MIB modules, 17.7.1 Definitions for the IEEE8021-TC-MIB module, and any associated introductory text) is conditional text “Not MIB Text”. To see this select some of this text and View>Panels>Conditional Tags (which can also be used to change conditional text marking). The Show/Hide Conditional Text panel (View>Show/Hide Conditional Text) can be used to move text with this tag from “Show” to “Hide” or vice versa. With this text moved to “Hide”, File>Save As…Save as type>Text only… can be used to save just the text of the MIB.In the “Save As Text” pop-up dialogue select Put a Carriage Return:Only between Paragraphs and Encoding:UTF-8. The resulting saved file needs to be further processed to remove the Byte Order Mark (BOM) which Windows add even to UTF-8 files, and to remove any “gremlins” (e.g. handed quote marks) that might be in the file. These can cause problems with some, though not all, MIB tools. The MAC applications BBEdit or TextWrangler have been used for this purpose, and the resulting cleaned up files saved with Unix LF (Line Feed) line breaks and UTF-8 (no BOM) encoding. The saved file is then renamed with a .mib extension.

MIB Text paragraph format and feathering

The actual MIB text in each of the MIB .fm files uses the paragraph format “Fixed Text”. This is use 8 pt Courier New with a Line Space of 9 pt, and no hyphenation. This font size and line spacing allows the use of the Framemaker auto line numbering capability, whereas tighter spacing can result in only the first line on a page being numbered. Numbering (Format>Document>Line Numbers ..) uses 7 pt Time Roman in Dark Grey, 19 pt width, numbering restarting on each page. To prevent line spacing being stretched on nearly full pages (which looks very odd in a MIB) Format>Page Layout>Line Layout is used to deselect “Feather”.

MIB LAST-UPDATED, MIB Copyright Year, Publication Year

The LAST-UPDATED field in each MIB uses the LAST-UPDATED variable for its .fm file, and this variable is also used in the latest REVISION statement within that MIB. Before changing this variable, the value in the soon-to-be-prior REVISION statement should be converted to plain text (select the variable in the REVISION statement and click on the convert to plain text icon in the Variables pod).

The MIB Copyright variable reflects the desired copyright date for the particular MIB – it may have been carried over unchanged from some prior amendment or revision, and the Publication Year variable reflects the anticipated publication year of the 802.1Q Revision containing the MIB.

YANG modules

The YANG modules for this standard have been developed and maintained using GitHub, as is customary for YANG development. Each YANG module is included in its own 48.6.n clause in 48.6, and is imported from the GitHub text file (File>Import File..) with “Copy into Document” generally preferred over “Import by Reference” to guard against accidental changes. The paragraph type “Fixed Text” (see discussion of MIBs above) is applied to the imported file, which is not independently editable in Frame.

The YANG schema (“tree files”) are similarly included in clause 48.5.

Files to be attached to the final pdf of the standard

In addition to the files required for the Framemaker book build, this file set contains the YANG module text files and the SNMP MIB modules to be attached to the standard. The YANG schema (“tree files”) are not to be attached.

The YANG module files are in the “YANG” subdirectory, and the MIB modules are in the 802-1Q-MIBs subdirectory.

P802.1Qdy – Editor Please Read