Guide to Converting Documents to MediaWiki

Revision as of 04:01, 18 February 2016 by Bbecane (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)


This document provides a guide for how to copy content from existing PDF (generated from Framemaker) documents to the Analytica Wiki, which uses Mediawiki (of which this page is an example). We are converting these documents:

General Guidelines

Headings

The Framemaker/PDF source documents are divided into Chapters, sections (bold red headings) and subsections (black headings). For the Analytica Tutorial, each chapter was converted into a page in the wiki. For the Analytica User Guide, normally each section becomes a page. Sometimes, if sections are very short, it may make sense to combine them with a preceding or following section with closely related topic into the same page.

Within a media wiki page, the top level Heading denoted with 1 equal sign "=" in Wikimarkup should never be used. Subheadings on a page should start with Sub-heading 1 (2 equal signs "==" in Wikimarkup).

The following table lists the different headings and what they correspond to across the Wiki Editors and in the PDF documents:

Visual Editor Heading Wikimarkup PDF Document Equivalent
N/A: New Page N/A: New Page Red Section Heading
Sub-heading 1 (Ctrl+3) == Sub-heading 1 == Black Subsection Heading
Sub-heading 2 (Ctrl+4) === Sub-heading 2 === Pull-out Heading

Many pages skip the subsections (black headings), but the Wiki should still use Sub-heading 2 for the black pull-out headings. If there are lists of pull-out headings corresponding to many short (1-2 lines) items then it is acceptable to insert the pull-out headings as bold text like so:

List of Pull-out headings Corresponding Wiki Text
Pdfpulloutlistexample.jpg Input arrows: Check to display arrows into this node.


Output arrows: Check to display arrows out of this node. By default, input and output arrows are not displayed for index and function nodes.

Label: Check to display the title in the node. By default, this is checked for all nodes.

Border: Check to display a thin black border around the node.

Example list is taken from Node Style dialog.

Chapters

Each Chapter from the Analytica User Guide should have its own main page, containing an introduction or overview, if there is one in the PDF, and a list of the section pages (links) in that chapter. Chapter pages should be titled "Chapter Name" and not "Chapter X: Chapter Name". A chapter page should start with some introductory text explaining what the chapter covers. This text can generally be taken from the Chapter Title page, which looks like this:

  • Document Chapter Page

After this introductory text there should be a Sub-heading 1 (==) called Sections which lists all of the pages contained within that chapter. The Result Tables and Graphs chapter is a good example of how Chapter Contents page should be formatted.

Table of Contents

The table of contents should always be placed at the top or near the top of each page. Only generic information or introductory text should come before a Table of Contents. The Wiki automatically generates the Table of Contents and places it before the first heading in the page, however, the Table of Contents can be inserted in any location using the Wiki Markup text __TOC__. Table of Contents should be manually moved to the top of pages that have a large amount of content before the first heading.

What to Add to Each Page

Each wiki page should contain these elements (in addition to content copied from original document):

  • Category: Each page should be located in the document category. For example, any page in the Analytica User Guide should also be located in the Category: Analytica User Guide page. Some pages may also be in additional categories, such as function types.
  • Breadcrumbs: The top of each page should include breadcrumbs that indicate where the page is located in the document, with links to its Chapter and document. For example, a page named Bananas located in the Fruits category of the Food document would have the following breadcrumbs at the top of the page's wiki-markup:
    • <breadcrumbs> Food > Fruits > {{PAGENAME}}</breadcrumbs>
  • Table of Contents: Manually insert the Table of Contents on pages that have a large amount of content before the first heading using the following markup:
    • __TOC__
  • See Also: After the last section in each page, add a See Also section with links to related pages:
    • ==See Also==
  • Footer: The bottom of each page should also include breadcrumbs linking to the previous and next page in this document. It should only link to pages within the same level and not pages contained within that page -- e.g. for a page Fruits containing Banana, the footer's previous and next pages might be Vegetables or Dairy, not Banana). If the preceeding pages were indeed Vegetables and Dairy, the footer would appear in the bottom of the page's wiki-markup:
    • <footer>Vegetables / {{PAGENAME}} / Dairy</footer>

Formats

Preserve standard character formats, including:

  • Formatting
    • Bold
    • Italics
    • Code snippets: Use <code> tags.
  • Tips: Tips are denoted in the text with the text Tip on the left-hand side and are contained within two horizontal red bars. There are custom tip tags that can be used on the Analytica Wiki to highlight these:
    • <tip title="Tip">This is the tip text</Tip>, which displays as:
    • Tip
      This is the tip text
  • Images or screenshots: It may be easiest to copy these using Snagit (or similar app to copy selected image from the original document), save them as png, and then upload them to the wiki. There is a facility to upload multiple images by dragging them into an area at the top of the section you are editing with the Source editor. (Not available in Visual editor.)
  • Analytica result Tables: Copy screenshots of Analytica results into the Wiki as images.
  • Tables of information: Enter actual tables in the Wiki as Wiki Tables. You can format Tables either as the default table style or using the Wiki Table formatting (the default in the Visual Editor). See examples of both below:

Tables

Tables should follow the same formatting, and when possible existing tables should be updated to follow this standardized format. The definition or variable name should always be on top of the table and in fixed-width text using the <code> tags. If the variable is being defined (e.g., "Let Variable_Name be ...") , then the text above the table should read:

Variable Variable_Name :=

If the table is the result of a function, then the text above the table should read:

Function(parameters) →

The arrow, such as in x → y should only be used to mean that expression x yields y.

2-D and 1-D indexes should be incorporated in the table, with index values and index names or identifiers in bold. Index names should be followed by ▶ or ▼ to denote which index labels (horizontal or vertical) the index name refers to. Vertical index names should go above the index values and to the left of the horizontal index values. Horizontal index names should go above the index values in a table cell as wide as the labels.

Tables can be formatted using either the default table style (when using the MediaWiki editor) or the Wiki Table formatting style (the default when using the Visual Editor). The following table example include both styles for reference.

Default Table Example

1-D Table setting Variable Definition

Variable Miles_per_gallon :=
Car_type ▶
VW Honda BMW
32 34 18

2-D Table with Function

MDTable(T, Rows, Cols, [Car_type, Mpg], 'average', 'n/a') →
Mpg ▶
Car_type ▼ 26 30 35
VW 2185 1705 n/a
Honda 2330 n/a 2210
BMW n/a 2955 2835

Wikitable Table Example

1-D Table setting Variable Definition

Variable Miles_per_gallon :=
Car_type ▶
VW Honda BMW
32 34 18

2-D Table with Function

MDTable(T, Rows, Cols, [Car_type, Mpg], 'average', 'n/a') →
Mpg ▶
Car_type ▼ 26 30 35
VW 2185 1705 n/a
Honda 2330 n/a 2210
BMW n/a 2955 2835

Sample Page Template

[[Category: Doc Name]]
<breadcrumbs> Doc Name > Chapter Name > {{PAGENAME}}</breadcrumbs>

This is introductory page content.
__TOC__

This is page content.

==Subheading==
Subheading content goes here.

===Subsection under Subheading==
Any text in a subsection within the subheading should go under here.

==Subheading 2==
Subheading 2 content goes here.

==See Also==
*Any appropriate links go here.

<footer>Number formats / {{PAGENAME}} / Next</footer>

Example Documents


See Also

Comments


You are not allowed to post comments.