bannerd

Quotations in SWEHB

 1. Introduction

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. 

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. 

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. 

Q1-SEI CERT Coding Standards.
some quote from SWEREF-004 ...

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. 

Quotes used in SWEs and Topics

3.3.2 - Display the quote from the SWE

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. 

report info

  • No labels