docgen-tool 2.1.2 → 3.0.0

package/source/user-guide/parameters.json

@@ -1,37 +1,37 @@
 {
-	"title" : "DocGen - a documentation tool",
-	"name": "DocGen",
-	"version" : "2.1.2",
-	"date" : "28/05/2015",
-	"organization" : {
-		"name" : "Mark Macdonald",
-		"url" : "https://github.com/mtmacdonald"
-	},
-	"author" : {
-		"name" : "Mark Macdonald",
-		"url" : "https://github.com/mtmacdonald"
-	},
-	"owner" : {
-		"name" : "Mark Macdonald",
-		"url" : "https://github.com/mtmacdonald"
-	},
-	"contributors" : [
-		{
-			"name" : "",
-			"url" : ""
-		}
-	],
-	"website" : {
-		"name" : "Github",
-		"url" : "https://github.com/mtmacdonald/docgen"
-	},
-	"backlink" : {
-		"name" : "",
-		"url" : ""
-	},
-	"module" : "",
-	"id" : "",
-	"summary" : "DocGen is a command-line documentation tool for software products. It takes plain text or CommonMark (Markdown) as input, and generates both a static website and a PDF copy.",
-	"marking" : "MIT License.",
-	"legalese" : ""
-}
+  "title": "DocGen - a documentation tool",
+  "name": "DocGen",
+  "version": "3.0.0",
+  "date": "24/06/2023",
+  "organization": {
+    "name": "Inkit Inc. and contributors",
+    "url": "https://www.inkit.com"
+  },
+  "author": {
+    "name": "Inkit Inc. and contributors",
+    "url": "https://www.inkit.com"
+  },
+  "owner": {
+    "name": "Inkit Inc.",
+    "url": "https://www.inkit.com"
+  },
+  "contributors": [
+    {
+      "name": "Mark Macdonald",
+      "url": "https://github.com/mtmacdonald"
+    }
+  ],
+  "website": {
+    "name": "Github",
+    "url": "https://github.com/mtmacdonald/docgen"
+  },
+  "backlink": {
+    "name": "",
+    "url": ""
+  },
+  "module": "",
+  "id": "",
+  "summary": "DocGen is a command-line documentation tool for software products. It takes plain text or CommonMark (Markdown) as input, and generates both a static website and a PDF copy.",
+  "marking": "MIT License.",
+  "legalese": ""
+}

package/source/user-guide/release-notes.txt

@@ -1,59 +1,70 @@
-DocGen 2.1.2 released 28/05/2015
---------------------------------
-
-- Fixed a regression defect (exception when running docgen scaffold) that first appeared in DocGen 2.1.0
-
-DocGen 2.1.1 released 28/05/2015
---------------------------------
-
-- Upgraded all node dependencies to the latest versions
-- Upgraded styles to the latest release of Webknife (1.4.0)
-
-DocGen 2.1.0 released 27/05/2015
---------------------------------
-
-- Added a command-line option for specifying a custom path to wkhtmltopdf
-
-DocGen 2.0.1 released 31/03/2015
---------------------------------
-
-- Fixed the node package and user guide for installing with npm install -g
-
-DocGen 2.0.0 released 31/03/2015
---------------------------------
-
-- DocGen is now open source
-- Rewritten in JavaScript for Node.js
-- Much easier to install (hosted on npm)
-- Dependencies are now version controlled (using npm)
-- Modernized visual style (uses Webknife CSS framework)
-- Input metadata files are now in JSON rather than YAML format
-- Top-level page headings are now inserted automatically (from contents.json)
-- The web and PDF tables of contents both correspond to contents.json
-- Command-line options are now used for configuration, rather than a config file
-- Command-line output is now color coded (green success, red error)
-- Added usage information to the command line interface
-- Generating the PDF is now an optional feature
-- Upgraded to the latest version of the PDF generator (wkhtmltopdf)
-- Added support for mathematical expressions (with KaTex or MathJax)
-- Added support for a list of document contributors (for multiple authors)
-- Added support for a header link back to the application (integrated docs)
-- Added time to the generation timestamp
-- Renamed 'change log' to 'release notes'
-- Fixed issues with fonts and text kerning in the PDF copy
-- Fixed defect where unexpected text appeared on some pages with a page table of contents
-- Dropped support for Internet Explorer 7 and 8
-- Dropped formal support for tool to run on multiple operating systems
-- Removed support for 'Mark of the Web'
-
-DocGen 1.0.1 released 18/01/2012
---------------------------------
-
-- Fixed a bug causing the table of contents headings to sometimes appear in the wrong order
-
-DocGen 1.0.0 released 04/11/2011
---------------------------------
-
-- Ruby implementation (not released as open source)
-- Creates a static website from Markdown input files
+DocGen 3.0.0 released 24/06/2024
+--------------------------------
+
+- Ownership and copyright transferred to project sponsor [Inkit Inc](https://www.inkit.com/)
+- License remains open-source MIT
+
+DocGen 2.1.3 released 29/05/2015
+--------------------------------
+
+- Allow more protocols in CommonMark links (see markdown-it [ticket #108](https://github.com/markdown-it/markdown-it/issues/108))
+
+DocGen 2.1.2 released 28/05/2015
+--------------------------------
+
+- Fixed a regression defect (exception when running docgen scaffold) that first appeared in DocGen 2.1.0
+
+DocGen 2.1.1 released 28/05/2015
+--------------------------------
+
+- Upgraded all node dependencies to the latest versions
+- Upgraded styles to the latest release of Webknife (1.4.0)
+
+DocGen 2.1.0 released 27/05/2015
+--------------------------------
+
+- Added a command-line option for specifying a custom path to wkhtmltopdf
+
+DocGen 2.0.1 released 31/03/2015
+--------------------------------
+
+- Fixed the node package and user guide for installing with npm install -g
+
+DocGen 2.0.0 released 31/03/2015
+--------------------------------
+
+- DocGen is now open source
+- Rewritten in JavaScript for Node.js
+- Much easier to install (hosted on npm)
+- Dependencies are now version controlled (using npm)
+- Modernized visual style (uses Webknife CSS framework)
+- Input metadata files are now in JSON rather than YAML format
+- Top-level page headings are now inserted automatically (from contents.json)
+- The web and PDF tables of contents both correspond to contents.json
+- Command-line options are now used for configuration, rather than a config file
+- Command-line output is now color coded (green success, red error)
+- Added usage information to the command line interface
+- Generating the PDF is now an optional feature
+- Upgraded to the latest version of the PDF generator (wkhtmltopdf)
+- Added support for mathematical expressions (with KaTex or MathJax)
+- Added support for a list of document contributors (for multiple authors)
+- Added support for a header link back to the application (integrated docs)
+- Added time to the generation timestamp
+- Renamed 'change log' to 'release notes'
+- Fixed issues with fonts and text kerning in the PDF copy
+- Fixed defect where unexpected text appeared on some pages with a page table of contents
+- Dropped support for Internet Explorer 7 and 8
+- Dropped formal support for tool to run on multiple operating systems
+- Removed support for 'Mark of the Web'
+
+DocGen 1.0.1 released 18/01/2012
+--------------------------------
+
+- Fixed a bug causing the table of contents headings to sometimes appear in the wrong order
+
+DocGen 1.0.0 released 04/11/2011
+--------------------------------
+
+- Ruby implementation (not released as open source)
+- Creates a static website from Markdown input files
 - Also creates a PDF copy using wkhtmltopdf

package/source/user-guide/running.txt

@@ -1,47 +1,47 @@
-Overview
---------
-
-DocGen is a command-line tool which takes plain text input files and outputs a static website.
-
-Command-line usage
-------------------
-
-The DocGen command-line interface includes usage help for both the tool and its subcommands:
-
-	docgen --help
-	docgen run --help
-
-Scaffold command
-----------------
-
-The **scaffold** command creates an *example* input directory. It outputs the minumum files required by DocGen, which 
-can then be used as a template for making any new website.
-
-**Create a scaffold template in the working directory** (./)**:**
-
-	docgen scaffold
-
-**Create a scaffold template in a specified directory:**
-
-	docgen scaffold -o $HOME/docgen-example
-
-Run command
------------
-
-The **run** command transforms an input directory (plain text source) into an output directory (HTML+PDF).
-
-**Basic usage:**
-
-	docgen run -i $HOME/docgen-example -o $HOME/docgen-output
-
-**Optionally create a PDF:**
-
-	docgen run -i $HOME/docgen-example -o $HOME/docgen-output -p
-
-**Optionally create a redirect page:**
-
-	docgen run -i $HOME/docgen-example -o $HOME/docgen-output -r
-
-> The optional redirect page is an 'index.html' file that is placed in the output's parent directory. The redirect page
-redirects the user to the homepage in the output directory. This is mostly useful for hosting the website without having
+Overview
+--------
+
+DocGen is a command-line tool which takes plain text input files and outputs a static website.
+
+Command-line usage
+------------------
+
+The DocGen command-line interface includes usage help for both the tool and its subcommands:
+
+	docgen --help
+	docgen run --help
+
+Scaffold command
+----------------
+
+The **scaffold** command creates an *example* input directory. It outputs the minumum files required by DocGen, which 
+can then be used as a template for making any new website.
+
+**Create a scaffold template in the working directory** (./)**:**
+
+	docgen scaffold
+
+**Create a scaffold template in a specified directory:**
+
+	docgen scaffold -o $HOME/docgen-example
+
+Run command
+-----------
+
+The **run** command transforms an input directory (plain text source) into an output directory (HTML+PDF).
+
+**Basic usage:**
+
+	docgen run -i $HOME/docgen-example -o $HOME/docgen-output
+
+**Optionally create a PDF:**
+
+	docgen run -i $HOME/docgen-example -o $HOME/docgen-output -p
+
+**Optionally create a redirect page:**
+
+	docgen run -i $HOME/docgen-example -o $HOME/docgen-output -r
+
+> The optional redirect page is an 'index.html' file that is placed in the output's parent directory. The redirect page
+redirects the user to the homepage in the output directory. This is mostly useful for hosting the website without having
 to place all the files in the root directory.

package/source/user-guide/troubleshooting.txt

@@ -1,32 +1,32 @@
-This section gives help on solving common issues with DocGen.
-
-Displaying detailed errors
---------------------------
-
-Pass the **-v** (verbose) option when running DocGen to get more detailed error messages.
-
-PDF missing content
--------------------
-
-In complex pages, the PDF generator (wkhtmltopdf) needs to be given enough time for dynamic content to be rendered. 
-Pass the **-d [milliseconds]** option to increase the rendering time for each page, if required.
-
-Attached files not in PDF
--------------------------
-
-Attached files are not converted to PDF, only the web content is.
-
-Corrupted text characters
--------------------------
-
-Make sure all the input text files are saved with UTF-8 encoding.
-
-Missing logo
-------------
-
-The logo must be PNG format and saved with the path *files/images/logo.png*. 
-
-Other issues
-------------
-
+This section gives help on solving common issues with DocGen.
+
+Displaying detailed errors
+--------------------------
+
+Pass the **-v** (verbose) option when running DocGen to get more detailed error messages.
+
+PDF missing content
+-------------------
+
+In complex pages, the PDF generator (wkhtmltopdf) needs to be given enough time for dynamic content to be rendered. 
+Pass the **-d [milliseconds]** option to increase the rendering time for each page, if required.
+
+Attached files not in PDF
+-------------------------
+
+Attached files are not converted to PDF, only the web content is.
+
+Corrupted text characters
+-------------------------
+
+Make sure all the input text files are saved with UTF-8 encoding.
+
+Missing logo
+------------
+
+The logo must be PNG format and saved with the path *files/images/logo.png*. 
+
+Other issues
+------------
+
 For any other problems, please submit a [an issue ticket](https://github.com/mtmacdonald/docgen/issues).

package/source/user-guide/upgrading.txt

@@ -1,25 +1,25 @@
-This section explains how to upgrade from old versions of DocGen.
-
-DocGen 1.0.* to DocGen 2.0.0
-----------------------------
-
-DocGen 2 is not backwards compatible with DocGen 1, but the upgrade is easy with these instructions:
-
-- Install DocGen 2 by following the [installation guide](installation.html)
-- Create a replacement 'source' directory, e.g: **<code>docgen scaffold -o $HOME/source</code>**
-- Migrate the source files
-	- Copy the source (.txt) files from the old 'Src' directory to the new 'source' directory
-	- Remove the top-level page headings in each source file (DocGen now inserts these automatically, based on contents.json)
-	- Rename *'change-log.txt'* to *'release-notes.txt'*
-- Migrate the attached content
-	- Place a logo with filename 'logo.png' in 'files/images' directory (the logo is now part of the source)
-	- Copy the images from *'Images'* to *'files/images'*
-	- Copy attached files from *'Files'* to *'files'*
-- Migrate the metadata
-	- Edit *'parameters.json'* with the relevant values from *'doc-parameters.yml'*
-	- Edit *'contents.json'* with the relevant values from *'table-of-contents.yml'*
-- Run DocGen: **<code>docgen -i $HOME/source -o $HOME/output</code>**
-- Check the styling in the latest version still works well with the old content
-- Note that the PDF is no longer generated by default (pass the *'-p'* option)
-
-> DocGen 1 tool-behaviours.yml has been replaced by command-line options. For help, see **<code>docgen run -h</code>**.
+This section explains how to upgrade from old versions of DocGen.
+
+DocGen 1.0.* to DocGen 2.0.0
+----------------------------
+
+DocGen 2 is not backwards compatible with DocGen 1, but the upgrade is easy with these instructions:
+
+- Install DocGen 2 by following the [installation guide](installation.html)
+- Create a replacement 'source' directory, e.g: **<code>docgen scaffold -o $HOME/source</code>**
+- Migrate the source files
+	- Copy the source (.txt) files from the old 'Src' directory to the new 'source' directory
+	- Remove the top-level page headings in each source file (DocGen now inserts these automatically, based on contents.json)
+	- Rename *'change-log.txt'* to *'release-notes.txt'*
+- Migrate the attached content
+	- Place a logo with filename 'logo.png' in 'files/images' directory (the logo is now part of the source)
+	- Copy the images from *'Images'* to *'files/images'*
+	- Copy attached files from *'Files'* to *'files'*
+- Migrate the metadata
+	- Edit *'parameters.json'* with the relevant values from *'doc-parameters.yml'*
+	- Edit *'contents.json'* with the relevant values from *'table-of-contents.yml'*
+- Run DocGen: **<code>docgen -i $HOME/source -o $HOME/output</code>**
+- Check the styling in the latest version still works well with the old content
+- Note that the PDF is no longer generated by default (pass the *'-p'* option)
+
+> DocGen 1 tool-behaviours.yml has been replaced by command-line options. For help, see **<code>docgen run -h</code>**.

package/source/user-guide/version-control.txt

@@ -1,13 +1,13 @@
-One of the benefits of using DocGen for product software documentation is that its plain text source files are easy to 
-version control in sync with the product.
-
-Recommended practice
---------------------
-
-It is recommended to store the documentation **source files** (DocGen input directory) in the same version control 
-repository as the product code. This allows each release of the product to have a matching version of its
-documentation.
-
-> It is not necessary to version control the DocGen output, because this can always be regenerated. If the DocGen
-output is version controlled, file renames, additions, and deletions have to be performed manually in the 
-version control tool.
+One of the benefits of using DocGen for product software documentation is that its plain text source files are easy to 
+version control in sync with the product.
+
+Recommended practice
+--------------------
+
+It is recommended to store the documentation **source files** (DocGen input directory) in the same version control 
+repository as the product code. This allows each release of the product to have a matching version of its
+documentation.
+
+> It is not necessary to version control the DocGen output, because this can always be regenerated. If the DocGen
+output is version controlled, file renames, additions, and deletions have to be performed manually in the 
+version control tool.