1. Introduction

Any document, NASA document or external document,  that is referred to in a SWEHB page is a reference.

Some references may not be directly called out in the text of the SWE page. These are "implied references. 

 1.1 Resources Tab

All SWE pages, and most Topic pages, have a Resources Tab. This tab was originally a container for two types of resources: References and Tools. See the SWE-000 - SWE Template or 0.0 Topic Template for formatting information of this tab. 

1.2 References Section

The References section contains a bullet list of documents mentioned in the page or appropriate to the content of the page. The following information is displayed for each reference: 

• SWEREF# - a sequential number that is the database key for the reference in the References Table in space 7150
• Title - The formal title of the reference given by the author
• Link - The URL that points to a copy of the reference, available on the network. The link is embedded in the title and is displayed as blue color in the title. 
• Citation - Author and Publisher information, may include the document number in the publishers library, also it can include the effective date and expiration date for the document. 
• Notes - Any other pertinent information such as a location in the document containing the material of interest. 

 The Tools Table section was used for listing tools that may be appropriate for use with the SWE or Topic. Starting in NPR 7150.2C the tools list has been suspended and the tools database is no longer beint maintained. 

 1.2 References Table

The References Table is a database of SWEREF pages that lives in the 7150 space. Each of the other SWEHB spaces has a References Table which displays its data from the 7150 space. 

Each SWEREF page is built using the the "reference" live template. This is a User Created Template and is based on the "reference" template stored in the 7150 space under Templates in the Space Tools of the Dashboard. 

  2. "Reference" Template

The "reference" template is part of the User Templates in the Confluence installation. It uses the Scaffolding Plugin to create data variables and capture values for these variables. A User Created Template called "reference" is stored in the 7150 space. It is this template that is used in SWEREF pages to define the data to be captured. 

 2.1 Source Code

The Source Code for this template is in Wiki Markup language: 

 2.2 Use in SWEREF page

Create In a SWEREF page using the naming convention SWEREF-999. The page should be a child of the References Table page in the 7150 space,

The easiest way to create a new SWEREF page is to:

• Open an existing SWEREF page (the one with the highest number in the active range in the References Table ).
• Use the Copy command to create a copy under the References Table page.
• When the copy of the page opens, immediately change the title to: 
  • remove "Copy of" 
  • change the number to be the next number in the series
• Save the new page. 
  • Verify that the page is saved and that the structure of the SWEREF is displayed in the table of the page.
  • Data values of the variables should all be blank at this point. 

Edit the new page and you should see the Live Template macro as the only thing on the page. The "reference" template is initiated by the "Live Template" macro. The parameters of the Live template are: 

• Type: template
• Template: reference

After saving the page. select "Edit Contents" from the page menu. This triggers the Scaffolding Plugin to organize the data elements in the page based on the structure described in the "reference" template code. You will be able to provide data for: 

• Link - use a fully qualified URL
• Title - This text will become the text for the URL link above. It is the title of the reference assigned by the author
• SWE or Topic - This is a comma delimited list of pages where the reference is used. 
  • SWE-999 - is the format for SWE pages. It comes from the first 7 characters of the SWE page title
  • Topic 9.88 - is the format for most Topic pages. Most topic pages are grouped into a single digit top-level, followed by a two digit sequence number. It comes from the first 4 characters of the topic page title. 
  • p99 - Principle page code. Assigned to Principles pages. 
  • xxxx - other codes used for document content pages. 
• Citation - this is a text field and may contain one or more of the following: 
  • Author(s),
  • Publisher,
  • Publisher's document Identification number,
  • Release date,
  • Effective date,
  • Expiration date, 
• Notes - Any other pertinent information such as a location in the document containing the material of interest. 

  3. "refstable" User Macros

There are several User Macros that are used to display references is the Resources tabs of SWEs and Topics. Each one is designed for a certain type of page: 

• refstable - used for SWE pages. It takes the first 7 characters of the SWE page to calculate a search key. The search key is used to search in the References Table pages to select SWEREFs that contain the search key anywhere in the Affiliated SWE field of the page. The selected pages are then sorted by SWEREF# and displayed as a bulleted list. 
• refstable-into - Used for references in the Introduction page only.  The key "Intro" is hard coded in the macro. 
• refstable-topic - Used for Topic pages. It takes the first 4 characters of the Topic page to calculate a search key. The search key is used to search in the References Table pages to select SWEREFs that contain the search key anywhere in the Affiliated SWE field of the page. The selected pages are then sorted by SWEREF# and displayed as a bulleted list. 
• Other classes of pages have hardcoded reference table reports. Including: 
  • Doc Page Resources - reports of references hardcoded by document type
  • Ref Reports - reports of references hardcoded by Principle. Stored under the Topics/Principles/Ref Reports page. 

4. Quoting From References

4.1 Short / Simple Quotes

Short quotes vary from a few words to a short sentence. They are included in-line in the text of a page in the traditional fashion. They are introduced by stating where the quote comes from (title of the reference), and then the quote itself in traditional quotation marks. If a reference is updated and possibly rewritten, some quotes are changed and may not be found verbatim in the updated version of the reference. 

4.2 Long Quotes

Long quotes vary from long complex sentences, to strings of sentence fragments (separated with ellipses) to a paragraph or more. These quotes are set apart from the rest of the text in the page in a special form. they are also documented in a special way so that they can be verified when the source reference is updated. 

The long quote is put into the body of a "Set-Data" macro which is set into the body of a Panel macro.

• The Set-Data macro uses two parameters
  • Name - 
  • Render - select "wiki"

5.

Alternative using Excerpt Macro

In the event that the "reference" template is broken and cannot be repaired, The following can be recovery can be used. 

5.1 Recover SWEREF Data

The SWEREF Recover Spreadsheet contains all the SWEREF data from the References Table. It contains data for : 

• Link
• Title
• Affiliated SWEs, topics and other codes
• Citations
• Notes

The spreadsheet will be updated quarterly and stored as an attachment to this page. 

5.2 Build Replacement

Each SWEREF page will be reused and rebuilt if the live template "reference" is broken. 

On each page perform the following steps: 

1. Remove the live template for "reference" - if is is broken, it is of no further value. 
2. Add an Excerpt macro at the top of the page. 
3. In the Excerpt macro configure the following body as a single bullet:
   • Title (as a link using the link data), Citation, Notes
4. Make the Excerpt display (not hidden)
5. Rebuild each page on which the SWEREF should appear (Affiliated SWEs)
   1. In the references section, add a Excerpt-Include macro pulling in the excerpts from each SWEREF that belongs in that page. 
6. Once all the SWEREFs are loaded for the page, move on to the next page. Do this for all spaces (7150, SWEHBVB, SWEHBVC, SWEHBVD, SITE): 
   1. all SWEs 
   2. all Topics
   3. all main pages such as Introduction
7. Add in the SWEREF page, the list of pages on which the SWEREF is published. This will help when updating references in the future. The "Page Information also contains a list of the pages which reference the SWEREF page.