Difference between revisions of "Guide to Converting Documents to MediaWiki"
Line 1: Line 1:
−
This document provides a guide for how to copy content from a PDF to the Analytica Wiki. Documents should ideally open to a Table of Contents page which links to a separate page for each chapter within the document. This document refers to each chapter page and the pages contained within those chapters.
+
This document provides a guide for how to copy content from existing PDF (Framemaker) documents to the Analytica Wiki, which uses Mediawiki (of which this page is an example). We want to convert these documents:
 +
* [[ADE User Guide]]: Completed.
 +
* [[Analytica Tutorial]]: Already completed, although may need to add some cross-references/links.
 +
* ''Analytica User Guide'': first 150 pp of 477 pages complete. Needs editing and cross-references.
 +
* ''Analytica Optimizer Guide'': 104 pp
  
 
==General Guidelines==
 
==General Guidelines==
−
Chapter pages will each have their own pages, as well as any Chapter Subsections (listed within each PDF documents' Table or Contents page and denoted within the text with Red Titles). Chapter pages should be titled "Chapter Name" and not "Chapter X: Chapter Name".
+
'''Dividing into wiki pages:''' The Framemaker/PDF source documents are divided into Chapters, sections (bold red headings) and subsections (black headings).  For the ''Tutorial'', each Chapter was converted into a page in the wiki.  For the ''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.
  
−
Headings for Media Wiki pages begin with second level headings (listed as Heading 1 in the Visual Editor, but denoted with 2 equal signs "==" in Wikimarkup).  
+
'''Chapters:''' Each Chapter from the ''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".
  
−
==What to Copy Over==
+
Headings for Media Wiki pages begin with second level headings, listed as '''Heading 1''' in the ''Visual Editor'', and denoted with 2 equal signs "==" in Wikimarkup.
 +
 
 +
== 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|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:
 +
**<code><nowiki><breadcrumbs> Food > Fruits > {{PAGENAME}}</breadcrumbs></nowiki></code>
 +
*'''See Also:''' After the last section in each page, add a '''See Also''' section with links to related pages:
 +
**<code><nowiki>==See Also==</nowiki></code>
 +
*'''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:
 +
**<code><nowiki><footer>Vegetables / {{PAGENAME}} / Dairy</footer></nowiki></code>
 +
 
 +
==Formats==
 +
Preserve standard character formats, including:
 
*Formatting
 
*Formatting
 
**Bold
 
**Bold
 
**Italics
 
**Italics
−
**Fixed-width text/code: This should be placed within <nowiki><code></nowiki> tags.
+
**Code snippets: Use <nowiki><code></nowiki> 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:
+
*'''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:
 
**<code><nowiki><tip title="Tip">This is the tip text</Tip></nowiki></code>, which displays as:
 
**<code><nowiki><tip title="Tip">This is the tip text</Tip></nowiki></code>, which displays as:
−
**<tip title="Tip">This is the tip text</Tip>
+
**<tip title="Tip">This is the tip text</tip>
−
*Images
+
*'''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 new facility to upload multiple images....)
−
*Tables: Screenshots of Analytica results should be copied into the Wiki as images, but actual tables in the Wiki should be entered in as Wiki Tables .Tables of results should have the corresponding function above the table in fixed-width text. Tables can either be formatted as the default table style or using the Wiki Table formatting (default in the Visual Editor). Examples of both are shown below:
+
*'''Analytica result Tables:''' Screenshots of Analytica results should be copied into the Wiki as images.
 +
*'''Tables of information:'''  Actual tables in the Wiki should be entered in as Wiki Tables. You can format Tables either as the default table style or using the Wiki Table formatting (default in the Visual Editor). See examples of both below:
  
 
===Default Table Example===
 
===Default Table Example===
Line 68: Line 86:
 
|2835
 
|2835
 
|}
 
|}
−
 
+
**
−
==What to Add to Each Page==
 
−
*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.
 
−
*Breadcrumbs: The top of each page should include breadcrumbs for where the page is located in the 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:
 
−
**<code><nowiki><breadcrumbs> Food > Fruits > {{PAGENAME}}</breadcrumbs></nowiki></code>
 
−
*See Also: After the last section in each page, a '''See Also''' section should also be added in.
 
−
**<code><nowiki>==See Also==</nowiki></code>
 
−
*Footer: The bottom of each page should also include breadcrumbs linking to the previous and next pages in the document. It should only link to pages within the same level and not pages contained within that page (i.e. 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:
 
−
**<code><nowiki><footer>Vegetables / {{PAGENAME}} / Dairy</footer></nowiki></code>
 
  
 
==Sample Page Template==
 
==Sample Page Template==

Revision as of 03:55, 16 October 2015

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

  • ADE User Guide: Completed.
  • Analytica Tutorial: Already completed, although may need to add some cross-references/links.
  • Analytica User Guide: first 150 pp of 477 pages complete. Needs editing and cross-references.
  • Analytica Optimizer Guide: 104 pp

General Guidelines

Dividing into wiki pages: The Framemaker/PDF source documents are divided into Chapters, sections (bold red headings) and subsections (black headings). For the Tutorial, each Chapter was converted into a page in the wiki. For the 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.

Chapters: Each Chapter from the 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".

Headings for Media Wiki pages begin with second level headings, listed as Heading 1 in the Visual Editor, and denoted with 2 equal signs "==" in Wikimarkup.

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>
  • 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 new facility to upload multiple images....)
  • Analytica result Tables: Screenshots of Analytica results should be copied into the Wiki as images.
  • Tables of information: Actual tables in the Wiki should be entered in as Wiki Tables. You can format Tables either as the default table style or using the Wiki Table formatting (default in the Visual Editor). See examples of both below:

Default Table Example

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

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 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

Comments


You are not allowed to post comments.