Quotations have been used in SWEHB since the first version. Quotes vary from short quotes of a few words or phrases, to long quotes of one or more long sentences or paragraphs.
1.1 Short Quotes
If the quotation is a short sentence, a sentence fragment, or a phrase, it may be put into the page surrounded by quotation marks. The attribution for the quote may be put either before or after the quote. The attribution should include the title of the document from which the quote is taken. The attribution will also be followed by a SWEREFN macro containing the 3 digit SWEREF number for the reference. All quotes should be taken from a properly referenced source. See References in SWEHB for details of creating and maintaining references.
1.2 Long Quotes
If the quotation is a long, complex sentence or more, it will be put into a "Set Data" macro so it can be tied properly to the reference it came from in the References Table database.
Div
id
tabs-2
2. Quotation Structure
2.1 In the SWEHB page containing the quote
In the SWEHB page, the quote is put into a Set Data macro contained within a Panel macro.
The panel macro serves to highlight the quote for the reader. It is set off with a blue border to make it distinctive and different from the Note panel which has a yellow border and yellow background.
The title of the panel contains the title of the reference from which the quotation is taken.
Inside of the panel are two macros:
Set Data macro contains the body of the quote and is named so that it can be used on other pages.
SWEREFN macro provides a link taking the reader to the Resources tab where a link to the reference can be found.
2.2 In the SWEREF page
When a quote is taken from a reference, is it important to identify it in the SWEREF page so that if the source document is changed, the new document can be reviewed to see if any changes were made to any of the items quoted in SWEHB pages.
2.3 Fragmented Quotations
In some cases a quotation will be built from two or more fragments with ellipses separating the fragments. This is done to exclude text that is superfluous and might confuse the reader. In the example below, The quotation is in 3 parts, taken from the opening paragraphs in the reference. The quotation in the SWE contains the fragments along with notes describing where the fragments are taken from.
To ensure that the text display does not run together, set the Render parameter to "wiki" in the Set Data macro. If it is text, the returns are removed when displaying the text and the text will all run together with no white space or new lines where you expect them.
Div
id
tabs-3
3. Adding a Quotation
A quote in a SWEHB page should be put into a "Set Data" macro contained in a Panel.
3.1 Panel Macro
To initiate the panel macro, start typing in the body of a page, "{pane". After a few characters a dropdown menu will appear, click on the Panel option. The panel macro frame will be displayed.
Click on the Panel header and open the "Edit" option.
In this example, the quote is taken from SWEREF-004 and is the first quote taken from this reference in this SWEHB page. Only 3 parameters are filled out -
Panel Title - set to "Q1 - title of the reference from which the quote is taken"
Border Title - blue
Save the macro
3.2 Set Data Macro
Inside of the Panel macro insert a "Set Data" macro. To initiate this macro, start typing "{Set Da" inside of the Panel. Select Set Data from the dropdown menu.
In the Set Data Macro, enter a name for the quote. The name should be in the form "Q9-888" where 9 is the sequential number for the quote, and 888 is hte 3 digit number of the SWEREF from which the quote is taken. In this case this is the first quote from SWEREF-004 on this page - "Q1-004".
Set the Render parameter to "wiki"
Finally, add a "{SWEREFN" macro with the 3 digit number of the SWEREF to complete the panel.
The completed panel will look like this.
Panel
borderColor
blue
title
Q1-SEI CERT Coding Standards.
Set Data
name
Q1-004
render
wiki
some quote from SWEREF-004 ...
Swerefn
refnum
004
3.3 Report Info Macro in the SWEREF page
3.3.1 Quotes used in SWEs and Topics
Once the Panel and Set Data are saved in the SWE page, you can go to the SWEREF page to complete the quote. In the SWEREF page, click on Edit. Below the Live Template and the Show If macros, start a new line in heading style 3. The line should be "Quotes used in SWEs and Topics". Below that, put in a link to the page containing the quote in a bulleted list. After the page link, describe
where the quote appears in the SWE or Topic page
where in the reference the quote is taken. use paragraph numbers of other means to identify location in the reference.
Below the bullet with the link to the SWE page, Start a Report Info macro with the command "{Report In".
After a few characters the dropdown menu should let you select the "Report Info" macro. In the parameter block:
Key - should "data:" followed by the Quote Name you created for the Set Data macro in the SWE. This is how the Report info selects the right data value.
Source - this value has two parts. The first part is the space where the SWE page exists, in this case it is SWEHBVD: followed by a colon. The second part is the full SWE page title. In the example below, the full Source is "SWEHBVD:SWE-002 - Software Engineering Initiative".
Render - "wiki"
The completed entry in SWEREF-038 looks like this.
