docgen-tool 2.1.2 → 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (81) hide show
  1. package/.gitattributes +1 -0
  2. package/.github/workflows/deploy-website.yml +28 -0
  3. package/.prettierignore +4 -0
  4. package/.prettierrc +4 -0
  5. package/LICENSE +35 -33
  6. package/{docgen → dist/docgen.js} +11 -22
  7. package/docgen.js +95 -0
  8. package/package.json +47 -20
  9. package/source/__test__/test-run/contents.json +12 -0
  10. package/source/__test__/test-run/overview.txt +3 -0
  11. package/source/__test__/test-run/parameters.json +32 -0
  12. package/source/__test__/test-run/release-notes.txt +4 -0
  13. package/source/docgen.js +900 -775
  14. package/source/example/contents.json +11 -11
  15. package/source/example/index.txt +3 -3
  16. package/source/example/parameters.json +36 -36
  17. package/source/internal-readme.md +4 -0
  18. package/source/pdf-stylesheet.css +26 -20
  19. package/source/require/docgen.css +76 -69
  20. package/source/require/katexInjector.js +9 -13
  21. package/source/require/print.css +26 -19
  22. package/source/templates/main.html +93 -93
  23. package/source/user-guide/advanced-content.txt +170 -170
  24. package/source/user-guide/contents.json +56 -56
  25. package/source/user-guide/files/images/svg/inkit-logo.svg +9 -0
  26. package/source/user-guide/index.txt +257 -244
  27. package/source/user-guide/installation.txt +49 -49
  28. package/source/user-guide/parameters.json +36 -36
  29. package/source/user-guide/release-notes.txt +69 -58
  30. package/source/user-guide/running.txt +46 -46
  31. package/source/user-guide/troubleshooting.txt +31 -31
  32. package/source/user-guide/upgrading.txt +25 -25
  33. package/source/user-guide/version-control.txt +13 -13
  34. package/source/user-guide/writing-content.txt +269 -269
  35. package/tsconfig.json +8 -0
  36. package/.npmignore +0 -2
  37. package/docs/advanced-content.html +0 -239
  38. package/docs/commonmark.html +0 -225
  39. package/docs/docgen.pdf +0 -0
  40. package/docs/files/images/overview.png +0 -0
  41. package/docs/files/images/pdf.png +0 -0
  42. package/docs/files/images/svg/icon.svg +0 -845
  43. package/docs/files/images/svg/overview.svg +0 -1345
  44. package/docs/files/images/text.png +0 -0
  45. package/docs/files/images/web.png +0 -0
  46. package/docs/index.html +0 -333
  47. package/docs/installation.html +0 -121
  48. package/docs/ownership.html +0 -164
  49. package/docs/release-notes.html +0 -144
  50. package/docs/require/docgen.css +0 -131
  51. package/docs/require/katex/fonts/KaTeX_AMS-Regular.woff +0 -0
  52. package/docs/require/katex/fonts/KaTeX_Main-Bold.woff +0 -0
  53. package/docs/require/katex/fonts/KaTeX_Main-Italic.woff +0 -0
  54. package/docs/require/katex/fonts/KaTeX_Main-Regular.woff +0 -0
  55. package/docs/require/katex/fonts/KaTeX_Math-BoldItalic.woff +0 -0
  56. package/docs/require/katex/fonts/KaTeX_Math-Italic.woff +0 -0
  57. package/docs/require/katex/fonts/KaTeX_Math-Regular.woff +0 -0
  58. package/docs/require/katex/fonts/KaTeX_Size1-Regular.woff +0 -0
  59. package/docs/require/katex/fonts/KaTeX_Size2-Regular.woff +0 -0
  60. package/docs/require/katex/fonts/KaTeX_Size3-Regular.woff +0 -0
  61. package/docs/require/katex/fonts/KaTeX_Size4-Regular.woff +0 -0
  62. package/docs/require/katex/katex.min.css +0 -1
  63. package/docs/require/katex/katex.min.js +0 -6
  64. package/docs/require/katexInjector.js +0 -22
  65. package/docs/require/print.css +0 -19
  66. package/docs/require/webknife/fonts/DroidSansMono.woff +0 -0
  67. package/docs/require/webknife/fonts/OpenSans.woff +0 -0
  68. package/docs/require/webknife/fonts/OpenSansBold.woff +0 -0
  69. package/docs/require/webknife/fonts/OpenSansBoldItalic.woff +0 -0
  70. package/docs/require/webknife/fonts/OpenSansItalic.woff +0 -0
  71. package/docs/require/webknife/framework.icons.js +0 -82
  72. package/docs/require/webknife/framework.min.css +0 -3
  73. package/docs/require/webknife/framework.min.js +0 -14
  74. package/docs/require/webknife/highlight.min.css +0 -1
  75. package/docs/require/webknife/highlight.min.js +0 -6
  76. package/docs/running.html +0 -123
  77. package/docs/troubleshooting.html +0 -105
  78. package/docs/upgrading.html +0 -124
  79. package/docs/version-control.html +0 -102
  80. package/docs/writing-content.html +0 -305
  81. /package/{docs → source/__test__/test-run}/files/images/logo.png +0 -0
package/docs/running.html DELETED
@@ -1,123 +0,0 @@
1
- <!doctype html>
2
- <html>
3
- <head>
4
- <meta http-equiv="X-UA-Compatible" content="IE=edge"><!--Prevent IE using compatibility mode on local or intranet pages. Do not put scripts before this line.-->
5
- <meta name="viewport" content="width=device-width, user-scalable=yes"><!--Mobile device scaling-->
6
- <meta charset="UTF-8">
7
- <title>DocGen - a documentation tool</title>
8
-
9
- <!--load stylesheets first (rationale: https://developers.google.com/speed/docs/best-practices/rtt#PutStylesBeforeScripts)-->
10
- <link rel="stylesheet" href="require/webknife/framework.min.css" type="text/css">
11
- <link rel="stylesheet" href="require/webknife/highlight.min.css" type="text/css">
12
- <link rel="stylesheet" href="require/docgen.css" type="text/css">
13
- <link rel="stylesheet" href="require/print.css" media="print">
14
-
15
- <!--load scripts second-->
16
-
17
- <script src="require/webknife/framework.min.js"></script>
18
- <script src="require/webknife/framework.icons.js"></script>
19
- <script src="require/webknife/highlight.min.js"></script>
20
-
21
- <!--inline scripts last-->
22
-
23
- <script type="text/javascript">
24
-
25
- $(document).ready( function () {
26
- $("#dg-toc").hide(); //hide the table of contents
27
-
28
- //instantiate an svg injector to show SVG icons
29
- var injector = new svgInject();
30
- injector.inject();
31
-
32
- //code syntax highlighting
33
- $('pre code, .w-inline-code').each(function(i, block) {
34
- hljs.highlightBlock(block);
35
- });
36
-
37
- //toggle visibility of table of contents
38
- $("#dg-navigator").click(function()
39
- {
40
- $("#dg-toc").slideToggle("fast");
41
- $(this).toggleClass("active");
42
- });
43
-
44
- });
45
- </script>
46
-
47
- <script type="text/x-mathjax-config">
48
- //MathJax configuration is the same as used by math.stackexchange.com
49
- MathJax.Hub.Config({"HTML-CSS": { preferredFont: "TeX", availableFonts: ["STIX","TeX"], linebreaks: { automatic:true }, EqnChunk: (MathJax.Hub.Browser.isMobile ? 10 : 50) },
50
- tex2jax: { inlineMath: [ ["$", "$"], ["\\\\(","\\\\)"] ], displayMath: [ ["$$","$$"], ["\\[", "\\]"] ], processEscapes: true, ignoreClass: "tex2jax_ignore|dno" },
51
- TeX: { noUndefined: { attributes: { mathcolor: "red", mathbackground: "#FFEEEE", mathsize: "90%" } }, Macros: { href: "{}" } },
52
- messageStyle: "none"
53
- });
54
- </script>
55
-
56
- <link rel="stylesheet" href="require/katex/katex.min.css" type="text/css"><script type="text/javascript" src="require/katex/katex.min.js"></script><script type="text/javascript" src="require/katexInjector.js"></script><script type="text/javascript" src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS_HTML-full"></script></head>
57
-
58
- <body>
59
-
60
- <div id="dg-toc"><div><table class="unstyled"><tr><td class="dg-tocGroup"><ul><li class="dg-tocHeading">Quick Start</li><li><a href="index.html">Overview</a></li><li><a href="installation.html">Installation</a></li><li><a href="upgrading.html">Upgrading</a></li></ul></td><td class="dg-tocGroup"><ul><li class="dg-tocHeading">User Guide</li><li><a href="running.html">Running DocGen</a></li><li><a href="writing-content.html">Writing content</a></li><li><a href="commonmark.html">CommonMark reference</a></li><li><a href="advanced-content.html">Advanced content</a></li></ul></td><td class="dg-tocGroup"><ul><li class="dg-tocHeading">Help</li><li><a href="troubleshooting.html">Troubleshooting</a></li><li><a href="version-control.html">Using with version control</a></li></ul></td><td class="dg-tocGroup"></td><td class="dg-tocGroup" id="dg-tocFixedColumn"><ul><li><span class="w-icon dg-tocIcon" data-name="person_group" title="archive"></span><a href="ownership.html">Ownership</a></li><li><span class="w-icon dg-tocIcon" data-name="refresh" title="archive"></span><a href="release-notes.html">Release Notes</a></li></ul><div><button class="w-icon-button" onclick="window.location=&apos;docgen.pdf&apos;;"><span class="w-icon" data-name="document"></span><span>PDF copy</span></button></div></td></tr></table></div></div>
61
- <div id="dg-navigator">Table of contents</div>
62
-
63
- <header>
64
- <div class="w-fixed-width">
65
- <a id="dg-homelink" href="index.html">
66
- <div id="dg-logo" style="background-image: url(files/images/logo.png); height: 42px; line-height: 42px; padding-left: 85px;">
67
- <span id="dg-title">DocGen - a documentation tool</span> <span id="dg-web-title-version" style="font-weight:normal;">(2.1.2)</span>
68
- </div>
69
- </a>
70
- <div>
71
- <span id="dg-backlink"></span>
72
- </div>
73
- </div>
74
- </header>
75
-
76
- <section id="dg-content"><div class="w-fixed-width"><div id="dg-innerContent"><h1 id="dg-autoTitle">Running DocGen</h1><ul class="dg-pageToc"><li><a href="#overview">Overview</a></li><li><a href="#command-line-usage">Command-line usage</a></li><li><a href="#scaffold-command">Scaffold command</a></li><li><a href="#run-command">Run command</a></li></ul><h2 id="overview">Overview</h2>
77
- <p>DocGen is a command-line tool which takes plain text input files and outputs a static website.</p>
78
- <h2 id="command-line-usage">Command-line usage</h2>
79
- <p>The DocGen command-line interface includes usage help for both the tool and its subcommands:</p>
80
- <pre><code>docgen --help
81
- docgen run --help
82
- </code></pre>
83
- <h2 id="scaffold-command">Scaffold command</h2>
84
- <p>The <strong>scaffold</strong> command creates an <em>example</em> input directory. It outputs the minumum files required by DocGen, which
85
- can then be used as a template for making any new website.</p>
86
- <p><strong>Create a scaffold template in the working directory</strong> (./)<strong>:</strong></p>
87
- <pre><code>docgen scaffold
88
- </code></pre>
89
- <p><strong>Create a scaffold template in a specified directory:</strong></p>
90
- <pre><code>docgen scaffold -o $HOME/docgen-example
91
- </code></pre>
92
- <h2 id="run-command">Run command</h2>
93
- <p>The <strong>run</strong> command transforms an input directory (plain text source) into an output directory (HTML+PDF).</p>
94
- <p><strong>Basic usage:</strong></p>
95
- <pre><code>docgen run -i $HOME/docgen-example -o $HOME/docgen-output
96
- </code></pre>
97
- <p><strong>Optionally create a PDF:</strong></p>
98
- <pre><code>docgen run -i $HOME/docgen-example -o $HOME/docgen-output -p
99
- </code></pre>
100
- <p><strong>Optionally create a redirect page:</strong></p>
101
- <pre><code>docgen run -i $HOME/docgen-example -o $HOME/docgen-output -r
102
- </code></pre>
103
- <blockquote>
104
- <p>The optional redirect page is an &apos;index.html&apos; file that is placed in the output&apos;s parent directory. The redirect page
105
- redirects the user to the homepage in the output directory. This is mostly useful for hosting the website without having
106
- to place all the files in the root directory.</p>
107
- </blockquote>
108
- </div></div></section>
109
-
110
- <footer>
111
- <div><p class="w-fixed-width"><span id="dg-web-footer">Version 2.1.2 released on 28/05/2015.</span></p></div>
112
- <div class="w-fixed-width">
113
- <p><span id="dg-copyright">&#xA9; 2015 <a href="https://github.com/mtmacdonald">Mark Macdonald</a></span></p>
114
- <p>
115
- <span id="dg-marking">MIT License.</span>
116
- <span id="dg-legalese"></span>
117
- <span id="dg-attribution">Created by DocGen 2.1.2 on 28/05/2015 at 18:31:56.</span>
118
- </p>
119
- </div>
120
- </footer>
121
-
122
- </body>
123
- </html>
package/docs/troubleshooting.html DELETED
@@ -1,105 +0,0 @@
1
- <!doctype html>
2
- <html>
3
- <head>
4
- <meta http-equiv="X-UA-Compatible" content="IE=edge"><!--Prevent IE using compatibility mode on local or intranet pages. Do not put scripts before this line.-->
5
- <meta name="viewport" content="width=device-width, user-scalable=yes"><!--Mobile device scaling-->
6
- <meta charset="UTF-8">
7
- <title>DocGen - a documentation tool</title>
8
-
9
- <!--load stylesheets first (rationale: https://developers.google.com/speed/docs/best-practices/rtt#PutStylesBeforeScripts)-->
10
- <link rel="stylesheet" href="require/webknife/framework.min.css" type="text/css">
11
- <link rel="stylesheet" href="require/webknife/highlight.min.css" type="text/css">
12
- <link rel="stylesheet" href="require/docgen.css" type="text/css">
13
- <link rel="stylesheet" href="require/print.css" media="print">
14
-
15
- <!--load scripts second-->
16
-
17
- <script src="require/webknife/framework.min.js"></script>
18
- <script src="require/webknife/framework.icons.js"></script>
19
- <script src="require/webknife/highlight.min.js"></script>
20
-
21
- <!--inline scripts last-->
22
-
23
- <script type="text/javascript">
24
-
25
- $(document).ready( function () {
26
- $("#dg-toc").hide(); //hide the table of contents
27
-
28
- //instantiate an svg injector to show SVG icons
29
- var injector = new svgInject();
30
- injector.inject();
31
-
32
- //code syntax highlighting
33
- $('pre code, .w-inline-code').each(function(i, block) {
34
- hljs.highlightBlock(block);
35
- });
36
-
37
- //toggle visibility of table of contents
38
- $("#dg-navigator").click(function()
39
- {
40
- $("#dg-toc").slideToggle("fast");
41
- $(this).toggleClass("active");
42
- });
43
-
44
- });
45
- </script>
46
-
47
- <script type="text/x-mathjax-config">
48
- //MathJax configuration is the same as used by math.stackexchange.com
49
- MathJax.Hub.Config({"HTML-CSS": { preferredFont: "TeX", availableFonts: ["STIX","TeX"], linebreaks: { automatic:true }, EqnChunk: (MathJax.Hub.Browser.isMobile ? 10 : 50) },
50
- tex2jax: { inlineMath: [ ["$", "$"], ["\\\\(","\\\\)"] ], displayMath: [ ["$$","$$"], ["\\[", "\\]"] ], processEscapes: true, ignoreClass: "tex2jax_ignore|dno" },
51
- TeX: { noUndefined: { attributes: { mathcolor: "red", mathbackground: "#FFEEEE", mathsize: "90%" } }, Macros: { href: "{}" } },
52
- messageStyle: "none"
53
- });
54
- </script>
55
-
56
- <link rel="stylesheet" href="require/katex/katex.min.css" type="text/css"><script type="text/javascript" src="require/katex/katex.min.js"></script><script type="text/javascript" src="require/katexInjector.js"></script><script type="text/javascript" src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS_HTML-full"></script></head>
57
-
58
- <body>
59
-
60
- <div id="dg-toc"><div><table class="unstyled"><tr><td class="dg-tocGroup"><ul><li class="dg-tocHeading">Quick Start</li><li><a href="index.html">Overview</a></li><li><a href="installation.html">Installation</a></li><li><a href="upgrading.html">Upgrading</a></li></ul></td><td class="dg-tocGroup"><ul><li class="dg-tocHeading">User Guide</li><li><a href="running.html">Running DocGen</a></li><li><a href="writing-content.html">Writing content</a></li><li><a href="commonmark.html">CommonMark reference</a></li><li><a href="advanced-content.html">Advanced content</a></li></ul></td><td class="dg-tocGroup"><ul><li class="dg-tocHeading">Help</li><li><a href="troubleshooting.html">Troubleshooting</a></li><li><a href="version-control.html">Using with version control</a></li></ul></td><td class="dg-tocGroup"></td><td class="dg-tocGroup" id="dg-tocFixedColumn"><ul><li><span class="w-icon dg-tocIcon" data-name="person_group" title="archive"></span><a href="ownership.html">Ownership</a></li><li><span class="w-icon dg-tocIcon" data-name="refresh" title="archive"></span><a href="release-notes.html">Release Notes</a></li></ul><div><button class="w-icon-button" onclick="window.location=&apos;docgen.pdf&apos;;"><span class="w-icon" data-name="document"></span><span>PDF copy</span></button></div></td></tr></table></div></div>
61
- <div id="dg-navigator">Table of contents</div>
62
-
63
- <header>
64
- <div class="w-fixed-width">
65
- <a id="dg-homelink" href="index.html">
66
- <div id="dg-logo" style="background-image: url(files/images/logo.png); height: 42px; line-height: 42px; padding-left: 85px;">
67
- <span id="dg-title">DocGen - a documentation tool</span> <span id="dg-web-title-version" style="font-weight:normal;">(2.1.2)</span>
68
- </div>
69
- </a>
70
- <div>
71
- <span id="dg-backlink"></span>
72
- </div>
73
- </div>
74
- </header>
75
-
76
- <section id="dg-content"><div class="w-fixed-width"><div id="dg-innerContent"><h1 id="dg-autoTitle">Troubleshooting</h1><ul class="dg-pageToc"><li><a href="#displaying-detailed-errors">Displaying detailed errors</a></li><li><a href="#pdf-missing-content">PDF missing content</a></li><li><a href="#attached-files-not-in-pdf">Attached files not in PDF</a></li><li><a href="#corrupted-text-characters">Corrupted text characters</a></li><li><a href="#missing-logo">Missing logo</a></li><li><a href="#other-issues">Other issues</a></li></ul><p>This section gives help on solving common issues with DocGen.</p>
77
- <h2 id="displaying-detailed-errors">Displaying detailed errors</h2>
78
- <p>Pass the <strong>-v</strong> (verbose) option when running DocGen to get more detailed error messages.</p>
79
- <h2 id="pdf-missing-content">PDF missing content</h2>
80
- <p>In complex pages, the PDF generator (wkhtmltopdf) needs to be given enough time for dynamic content to be rendered.
81
- Pass the <strong>-d [milliseconds]</strong> option to increase the rendering time for each page, if required.</p>
82
- <h2 id="attached-files-not-in-pdf">Attached files not in PDF</h2>
83
- <p>Attached files are not converted to PDF, only the web content is.</p>
84
- <h2 id="corrupted-text-characters">Corrupted text characters</h2>
85
- <p>Make sure all the input text files are saved with UTF-8 encoding.</p>
86
- <h2 id="missing-logo">Missing logo</h2>
87
- <p>The logo must be PNG format and saved with the path <em>files/images/logo.png</em>.</p>
88
- <h2 id="other-issues">Other issues</h2>
89
- <p>For any other problems, please submit a <a href="https://github.com/mtmacdonald/docgen/issues">an issue ticket</a>.</p>
90
- </div></div></section>
91
-
92
- <footer>
93
- <div><p class="w-fixed-width"><span id="dg-web-footer">Version 2.1.2 released on 28/05/2015.</span></p></div>
94
- <div class="w-fixed-width">
95
- <p><span id="dg-copyright">&#xA9; 2015 <a href="https://github.com/mtmacdonald">Mark Macdonald</a></span></p>
96
- <p>
97
- <span id="dg-marking">MIT License.</span>
98
- <span id="dg-legalese"></span>
99
- <span id="dg-attribution">Created by DocGen 2.1.2 on 28/05/2015 at 18:31:56.</span>
100
- </p>
101
- </div>
102
- </footer>
103
-
104
- </body>
105
- </html>
package/docs/upgrading.html DELETED
@@ -1,124 +0,0 @@
1
- <!doctype html>
2
- <html>
3
- <head>
4
- <meta http-equiv="X-UA-Compatible" content="IE=edge"><!--Prevent IE using compatibility mode on local or intranet pages. Do not put scripts before this line.-->
5
- <meta name="viewport" content="width=device-width, user-scalable=yes"><!--Mobile device scaling-->
6
- <meta charset="UTF-8">
7
- <title>DocGen - a documentation tool</title>
8
-
9
- <!--load stylesheets first (rationale: https://developers.google.com/speed/docs/best-practices/rtt#PutStylesBeforeScripts)-->
10
- <link rel="stylesheet" href="require/webknife/framework.min.css" type="text/css">
11
- <link rel="stylesheet" href="require/webknife/highlight.min.css" type="text/css">
12
- <link rel="stylesheet" href="require/docgen.css" type="text/css">
13
- <link rel="stylesheet" href="require/print.css" media="print">
14
-
15
- <!--load scripts second-->
16
-
17
- <script src="require/webknife/framework.min.js"></script>
18
- <script src="require/webknife/framework.icons.js"></script>
19
- <script src="require/webknife/highlight.min.js"></script>
20
-
21
- <!--inline scripts last-->
22
-
23
- <script type="text/javascript">
24
-
25
- $(document).ready( function () {
26
- $("#dg-toc").hide(); //hide the table of contents
27
-
28
- //instantiate an svg injector to show SVG icons
29
- var injector = new svgInject();
30
- injector.inject();
31
-
32
- //code syntax highlighting
33
- $('pre code, .w-inline-code').each(function(i, block) {
34
- hljs.highlightBlock(block);
35
- });
36
-
37
- //toggle visibility of table of contents
38
- $("#dg-navigator").click(function()
39
- {
40
- $("#dg-toc").slideToggle("fast");
41
- $(this).toggleClass("active");
42
- });
43
-
44
- });
45
- </script>
46
-
47
- <script type="text/x-mathjax-config">
48
- //MathJax configuration is the same as used by math.stackexchange.com
49
- MathJax.Hub.Config({"HTML-CSS": { preferredFont: "TeX", availableFonts: ["STIX","TeX"], linebreaks: { automatic:true }, EqnChunk: (MathJax.Hub.Browser.isMobile ? 10 : 50) },
50
- tex2jax: { inlineMath: [ ["$", "$"], ["\\\\(","\\\\)"] ], displayMath: [ ["$$","$$"], ["\\[", "\\]"] ], processEscapes: true, ignoreClass: "tex2jax_ignore|dno" },
51
- TeX: { noUndefined: { attributes: { mathcolor: "red", mathbackground: "#FFEEEE", mathsize: "90%" } }, Macros: { href: "{}" } },
52
- messageStyle: "none"
53
- });
54
- </script>
55
-
56
- <link rel="stylesheet" href="require/katex/katex.min.css" type="text/css"><script type="text/javascript" src="require/katex/katex.min.js"></script><script type="text/javascript" src="require/katexInjector.js"></script><script type="text/javascript" src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS_HTML-full"></script></head>
57
-
58
- <body>
59
-
60
- <div id="dg-toc"><div><table class="unstyled"><tr><td class="dg-tocGroup"><ul><li class="dg-tocHeading">Quick Start</li><li><a href="index.html">Overview</a></li><li><a href="installation.html">Installation</a></li><li><a href="upgrading.html">Upgrading</a></li></ul></td><td class="dg-tocGroup"><ul><li class="dg-tocHeading">User Guide</li><li><a href="running.html">Running DocGen</a></li><li><a href="writing-content.html">Writing content</a></li><li><a href="commonmark.html">CommonMark reference</a></li><li><a href="advanced-content.html">Advanced content</a></li></ul></td><td class="dg-tocGroup"><ul><li class="dg-tocHeading">Help</li><li><a href="troubleshooting.html">Troubleshooting</a></li><li><a href="version-control.html">Using with version control</a></li></ul></td><td class="dg-tocGroup"></td><td class="dg-tocGroup" id="dg-tocFixedColumn"><ul><li><span class="w-icon dg-tocIcon" data-name="person_group" title="archive"></span><a href="ownership.html">Ownership</a></li><li><span class="w-icon dg-tocIcon" data-name="refresh" title="archive"></span><a href="release-notes.html">Release Notes</a></li></ul><div><button class="w-icon-button" onclick="window.location=&apos;docgen.pdf&apos;;"><span class="w-icon" data-name="document"></span><span>PDF copy</span></button></div></td></tr></table></div></div>
61
- <div id="dg-navigator">Table of contents</div>
62
-
63
- <header>
64
- <div class="w-fixed-width">
65
- <a id="dg-homelink" href="index.html">
66
- <div id="dg-logo" style="background-image: url(files/images/logo.png); height: 42px; line-height: 42px; padding-left: 85px;">
67
- <span id="dg-title">DocGen - a documentation tool</span> <span id="dg-web-title-version" style="font-weight:normal;">(2.1.2)</span>
68
- </div>
69
- </a>
70
- <div>
71
- <span id="dg-backlink"></span>
72
- </div>
73
- </div>
74
- </header>
75
-
76
- <section id="dg-content"><div class="w-fixed-width"><div id="dg-innerContent"><h1 id="dg-autoTitle">Upgrading</h1><ul class="dg-pageToc"><li><a href="#docgen-1.0.*-to-docgen-2.0.0">DocGen 1.0.* to DocGen 2.0.0</a></li></ul><p>This section explains how to upgrade from old versions of DocGen.</p>
77
- <h2 id="docgen-1.0.*-to-docgen-2.0.0">DocGen 1.0.* to DocGen 2.0.0</h2>
78
- <p>DocGen 2 is not backwards compatible with DocGen 1, but the upgrade is easy with these instructions:</p>
79
- <ul>
80
- <li>Install DocGen 2 by following the <a href="installation.html">installation guide</a></li>
81
- <li>Create a replacement &apos;source&apos; directory, e.g: <strong><code>docgen scaffold -o $HOME/source</code></strong></li>
82
- <li>Migrate the source files
83
- <ul>
84
- <li>Copy the source (.txt) files from the old &apos;Src&apos; directory to the new &apos;source&apos; directory</li>
85
- <li>Remove the top-level page headings in each source file (DocGen now inserts these automatically, based on contents.json)</li>
86
- <li>Rename <em>&apos;change-log.txt&apos;</em> to <em>&apos;release-notes.txt&apos;</em></li>
87
- </ul>
88
- </li>
89
- <li>Migrate the attached content
90
- <ul>
91
- <li>Place a logo with filename &apos;logo.png&apos; in &apos;files/images&apos; directory (the logo is now part of the source)</li>
92
- <li>Copy the images from <em>&apos;Images&apos;</em> to <em>&apos;files/images&apos;</em></li>
93
- <li>Copy attached files from <em>&apos;Files&apos;</em> to <em>&apos;files&apos;</em></li>
94
- </ul>
95
- </li>
96
- <li>Migrate the metadata
97
- <ul>
98
- <li>Edit <em>&apos;parameters.json&apos;</em> with the relevant values from <em>&apos;doc-parameters.yml&apos;</em></li>
99
- <li>Edit <em>&apos;contents.json&apos;</em> with the relevant values from <em>&apos;table-of-contents.yml&apos;</em></li>
100
- </ul>
101
- </li>
102
- <li>Run DocGen: <strong><code>docgen -i $HOME/source -o $HOME/output</code></strong></li>
103
- <li>Check the styling in the latest version still works well with the old content</li>
104
- <li>Note that the PDF is no longer generated by default (pass the <em>&apos;-p&apos;</em> option)</li>
105
- </ul>
106
- <blockquote>
107
- <p>DocGen 1 tool-behaviours.yml has been replaced by command-line options. For help, see <strong><code>docgen run -h</code></strong>.</p>
108
- </blockquote>
109
- </div></div></section>
110
-
111
- <footer>
112
- <div><p class="w-fixed-width"><span id="dg-web-footer">Version 2.1.2 released on 28/05/2015.</span></p></div>
113
- <div class="w-fixed-width">
114
- <p><span id="dg-copyright">&#xA9; 2015 <a href="https://github.com/mtmacdonald">Mark Macdonald</a></span></p>
115
- <p>
116
- <span id="dg-marking">MIT License.</span>
117
- <span id="dg-legalese"></span>
118
- <span id="dg-attribution">Created by DocGen 2.1.2 on 28/05/2015 at 18:31:56.</span>
119
- </p>
120
- </div>
121
- </footer>
122
-
123
- </body>
124
- </html>
package/docs/version-control.html DELETED
@@ -1,102 +0,0 @@
1
- <!doctype html>
2
- <html>
3
- <head>
4
- <meta http-equiv="X-UA-Compatible" content="IE=edge"><!--Prevent IE using compatibility mode on local or intranet pages. Do not put scripts before this line.-->
5
- <meta name="viewport" content="width=device-width, user-scalable=yes"><!--Mobile device scaling-->
6
- <meta charset="UTF-8">
7
- <title>DocGen - a documentation tool</title>
8
-
9
- <!--load stylesheets first (rationale: https://developers.google.com/speed/docs/best-practices/rtt#PutStylesBeforeScripts)-->
10
- <link rel="stylesheet" href="require/webknife/framework.min.css" type="text/css">
11
- <link rel="stylesheet" href="require/webknife/highlight.min.css" type="text/css">
12
- <link rel="stylesheet" href="require/docgen.css" type="text/css">
13
- <link rel="stylesheet" href="require/print.css" media="print">
14
-
15
- <!--load scripts second-->
16
-
17
- <script src="require/webknife/framework.min.js"></script>
18
- <script src="require/webknife/framework.icons.js"></script>
19
- <script src="require/webknife/highlight.min.js"></script>
20
-
21
- <!--inline scripts last-->
22
-
23
- <script type="text/javascript">
24
-
25
- $(document).ready( function () {
26
- $("#dg-toc").hide(); //hide the table of contents
27
-
28
- //instantiate an svg injector to show SVG icons
29
- var injector = new svgInject();
30
- injector.inject();
31
-
32
- //code syntax highlighting
33
- $('pre code, .w-inline-code').each(function(i, block) {
34
- hljs.highlightBlock(block);
35
- });
36
-
37
- //toggle visibility of table of contents
38
- $("#dg-navigator").click(function()
39
- {
40
- $("#dg-toc").slideToggle("fast");
41
- $(this).toggleClass("active");
42
- });
43
-
44
- });
45
- </script>
46
-
47
- <script type="text/x-mathjax-config">
48
- //MathJax configuration is the same as used by math.stackexchange.com
49
- MathJax.Hub.Config({"HTML-CSS": { preferredFont: "TeX", availableFonts: ["STIX","TeX"], linebreaks: { automatic:true }, EqnChunk: (MathJax.Hub.Browser.isMobile ? 10 : 50) },
50
- tex2jax: { inlineMath: [ ["$", "$"], ["\\\\(","\\\\)"] ], displayMath: [ ["$$","$$"], ["\\[", "\\]"] ], processEscapes: true, ignoreClass: "tex2jax_ignore|dno" },
51
- TeX: { noUndefined: { attributes: { mathcolor: "red", mathbackground: "#FFEEEE", mathsize: "90%" } }, Macros: { href: "{}" } },
52
- messageStyle: "none"
53
- });
54
- </script>
55
-
56
- <link rel="stylesheet" href="require/katex/katex.min.css" type="text/css"><script type="text/javascript" src="require/katex/katex.min.js"></script><script type="text/javascript" src="require/katexInjector.js"></script><script type="text/javascript" src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS_HTML-full"></script></head>
57
-
58
- <body>
59
-
60
- <div id="dg-toc"><div><table class="unstyled"><tr><td class="dg-tocGroup"><ul><li class="dg-tocHeading">Quick Start</li><li><a href="index.html">Overview</a></li><li><a href="installation.html">Installation</a></li><li><a href="upgrading.html">Upgrading</a></li></ul></td><td class="dg-tocGroup"><ul><li class="dg-tocHeading">User Guide</li><li><a href="running.html">Running DocGen</a></li><li><a href="writing-content.html">Writing content</a></li><li><a href="commonmark.html">CommonMark reference</a></li><li><a href="advanced-content.html">Advanced content</a></li></ul></td><td class="dg-tocGroup"><ul><li class="dg-tocHeading">Help</li><li><a href="troubleshooting.html">Troubleshooting</a></li><li><a href="version-control.html">Using with version control</a></li></ul></td><td class="dg-tocGroup"></td><td class="dg-tocGroup" id="dg-tocFixedColumn"><ul><li><span class="w-icon dg-tocIcon" data-name="person_group" title="archive"></span><a href="ownership.html">Ownership</a></li><li><span class="w-icon dg-tocIcon" data-name="refresh" title="archive"></span><a href="release-notes.html">Release Notes</a></li></ul><div><button class="w-icon-button" onclick="window.location=&apos;docgen.pdf&apos;;"><span class="w-icon" data-name="document"></span><span>PDF copy</span></button></div></td></tr></table></div></div>
61
- <div id="dg-navigator">Table of contents</div>
62
-
63
- <header>
64
- <div class="w-fixed-width">
65
- <a id="dg-homelink" href="index.html">
66
- <div id="dg-logo" style="background-image: url(files/images/logo.png); height: 42px; line-height: 42px; padding-left: 85px;">
67
- <span id="dg-title">DocGen - a documentation tool</span> <span id="dg-web-title-version" style="font-weight:normal;">(2.1.2)</span>
68
- </div>
69
- </a>
70
- <div>
71
- <span id="dg-backlink"></span>
72
- </div>
73
- </div>
74
- </header>
75
-
76
- <section id="dg-content"><div class="w-fixed-width"><div id="dg-innerContent"><h1 id="dg-autoTitle">Using with version control</h1><ul class="dg-pageToc"><li><a href="#recommended-practice">Recommended practice</a></li></ul><p>One of the benefits of using DocGen for product software documentation is that its plain text source files are easy to
77
- version control in sync with the product.</p>
78
- <h2 id="recommended-practice">Recommended practice</h2>
79
- <p>It is recommended to store the documentation <strong>source files</strong> (DocGen input directory) in the same version control
80
- repository as the product code. This allows each release of the product to have a matching version of its
81
- documentation.</p>
82
- <blockquote>
83
- <p>It is not necessary to version control the DocGen output, because this can always be regenerated. If the DocGen
84
- output is version controlled, file renames, additions, and deletions have to be performed manually in the
85
- version control tool.</p>
86
- </blockquote>
87
- </div></div></section>
88
-
89
- <footer>
90
- <div><p class="w-fixed-width"><span id="dg-web-footer">Version 2.1.2 released on 28/05/2015.</span></p></div>
91
- <div class="w-fixed-width">
92
- <p><span id="dg-copyright">&#xA9; 2015 <a href="https://github.com/mtmacdonald">Mark Macdonald</a></span></p>
93
- <p>
94
- <span id="dg-marking">MIT License.</span>
95
- <span id="dg-legalese"></span>
96
- <span id="dg-attribution">Created by DocGen 2.1.2 on 28/05/2015 at 18:31:56.</span>
97
- </p>
98
- </div>
99
- </footer>
100
-
101
- </body>
102
- </html>