means each individual or legal entity that creates, contributes to the creation of, or owns Covered Software.
82 |
83 |
1.2. “Contributor Version”
84 |
means the combination of the Contributions of others (if any) used by a Contributor and that particular Contributor’s Contribution.
85 |
86 |
1.3. “Contribution”
87 |
means Covered Software of a particular Contributor.
88 |
89 |
1.4. “Covered Software”
90 |
means Source Code Form to which the initial Contributor has attached the notice in Exhibit A, the Executable Form of such Source Code Form, and Modifications of such Source Code Form, in each case including portions thereof.
91 |
92 |
1.5. “Incompatible With Secondary Licenses”
93 |
means
94 |
95 |
that the initial Contributor has attached the notice described in Exhibit B to the Covered Software; or
96 |
that the Covered Software was made available under the terms of version 1.1 or earlier of the License, but not also under the terms of a Secondary License.
97 |
98 |
99 |
1.6. “Executable Form”
100 |
means any form of the work other than Source Code Form.
101 |
102 |
1.7. “Larger Work”
103 |
means a work that combines Covered Software with other material, in a separate file or files, that is not Covered Software.
104 |
105 |
1.8. “License”
106 |
means this document.
107 |
108 |
1.9. “Licensable”
109 |
means having the right to grant, to the maximum extent possible, whether at the time of the initial grant or subsequently, any and all of the rights conveyed by this License.
110 |
111 |
1.10. “Modifications”
112 |
means any of the following:
113 |
114 |
any file in Source Code Form that results from an addition to, deletion from, or modification of the contents of Covered Software; or
115 |
any new file in Source Code Form that contains any Covered Software.
116 |
117 |
118 |
1.11. “Patent Claims” of a Contributor
119 |
means any patent claim(s), including without limitation, method, process, and apparatus claims, in any patent Licensable by such Contributor that would be infringed, but for the grant of the License, by the making, using, selling, offering for sale, having made, import, or transfer of either its Contributions or its Contributor Version.
120 |
121 |
1.12. “Secondary License”
122 |
means either the GNU General Public License, Version 2.0, the GNU Lesser General Public License, Version 2.1, the GNU Affero General Public License, Version 3.0, or any later versions of those licenses.
123 |
124 |
1.13. “Source Code Form”
125 |
means the form of the work preferred for making modifications.
126 |
127 |
1.14. “You” (or “Your”)
128 |
means an individual or a legal entity exercising rights under this License. For legal entities, “You” includes any entity that controls, is controlled by, or is under common control with You. For purposes of this definition, “control” means (a) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (b) ownership of more than fifty percent (50%) of the outstanding shares or beneficial ownership of such entity.
129 |
130 |
131 |
2. License Grants and Conditions
132 |
2.1. Grants
133 |
Each Contributor hereby grants You a world-wide, royalty-free, non-exclusive license:
134 |
135 |
under intellectual property rights (other than patent or trademark) Licensable by such Contributor to use, reproduce, make available, modify, display, perform, distribute, and otherwise exploit its Contributions, either on an unmodified basis, with Modifications, or as part of a Larger Work; and
136 |
under Patent Claims of such Contributor to make, use, sell, offer for sale, have made, import, and otherwise transfer either its Contributions or its Contributor Version.
137 |
138 |
2.2. Effective Date
139 |
The licenses granted in Section 2.1 with respect to any Contribution become effective for each Contribution on the date the Contributor first distributes such Contribution.
140 |
2.3. Limitations on Grant Scope
141 |
The licenses granted in this Section 2 are the only rights granted under this License. No additional rights or licenses will be implied from the distribution or licensing of Covered Software under this License. Notwithstanding Section 2.1(b) above, no patent license is granted by a Contributor:
142 |
143 |
for any code that a Contributor has removed from Covered Software; or
144 |
for infringements caused by: (i) Your and any other third party’s modifications of Covered Software, or (ii) the combination of its Contributions with other software (except as part of its Contributor Version); or
145 |
under Patent Claims infringed by Covered Software in the absence of its Contributions.
146 |
147 |
This License does not grant any rights in the trademarks, service marks, or logos of any Contributor (except as may be necessary to comply with the notice requirements in Section 3.4).
148 |
2.4. Subsequent Licenses
149 |
No Contributor makes additional grants as a result of Your choice to distribute the Covered Software under a subsequent version of this License (see Section 10.2) or under the terms of a Secondary License (if permitted under the terms of Section 3.3).
150 |
2.5. Representation
151 |
Each Contributor represents that the Contributor believes its Contributions are its original creation(s) or it has sufficient rights to grant the rights to its Contributions conveyed by this License.
152 |
2.6. Fair Use
153 |
This License is not intended to limit any rights You have under applicable copyright doctrines of fair use, fair dealing, or other equivalents.
154 |
2.7. Conditions
155 |
Sections 3.1, 3.2, 3.3, and 3.4 are conditions of the licenses granted in Section 2.1.
156 |
3. Responsibilities
157 |
3.1. Distribution of Source Form
158 |
All distribution of Covered Software in Source Code Form, including any Modifications that You create or to which You contribute, must be under the terms of this License. You must inform recipients that the Source Code Form of the Covered Software is governed by the terms of this License, and how they can obtain a copy of this License. You may not attempt to alter or restrict the recipients’ rights in the Source Code Form.
159 |
3.2. Distribution of Executable Form
160 |
If You distribute Covered Software in Executable Form then:
161 |
162 |
such Covered Software must also be made available in Source Code Form, as described in Section 3.1, and You must inform recipients of the Executable Form how they can obtain a copy of such Source Code Form by reasonable means in a timely manner, at a charge no more than the cost of distribution to the recipient; and
163 |
You may distribute such Executable Form under the terms of this License, or sublicense it under different terms, provided that the license for the Executable Form does not attempt to limit or alter the recipients’ rights in the Source Code Form under this License.
164 |
165 |
3.3. Distribution of a Larger Work
166 |
You may create and distribute a Larger Work under terms of Your choice, provided that You also comply with the requirements of this License for the Covered Software. If the Larger Work is a combination of Covered Software with a work governed by one or more Secondary Licenses, and the Covered Software is not Incompatible With Secondary Licenses, this License permits You to additionally distribute such Covered Software under the terms of such Secondary License(s), so that the recipient of the Larger Work may, at their option, further distribute the Covered Software under the terms of either this License or such Secondary License(s).
167 |
3.4. Notices
168 |
You may not remove or alter the substance of any license notices (including copyright notices, patent notices, disclaimers of warranty, or limitations of liability) contained within the Source Code Form of the Covered Software, except that You may alter any license notices to the extent required to remedy known factual inaccuracies.
169 |
3.5. Application of Additional Terms
170 |
You may choose to offer, and to charge a fee for, warranty, support, indemnity or liability obligations to one or more recipients of Covered Software. However, You may do so only on Your own behalf, and not on behalf of any Contributor. You must make it absolutely clear that any such warranty, support, indemnity, or liability obligation is offered by You alone, and You hereby agree to indemnify every Contributor for any liability incurred by such Contributor as a result of warranty, support, indemnity or liability terms You offer. You may include additional disclaimers of warranty and limitations of liability specific to any jurisdiction.
171 |
4. Inability to Comply Due to Statute or Regulation
172 |
If it is impossible for You to comply with any of the terms of this License with respect to some or all of the Covered Software due to statute, judicial order, or regulation then You must: (a) comply with the terms of this License to the maximum extent possible; and (b) describe the limitations and the code they affect. Such description must be placed in a text file included with all distributions of the Covered Software under this License. Except to the extent prohibited by statute or regulation, such description must be sufficiently detailed for a recipient of ordinary skill to be able to understand it.
173 |
5. Termination
174 |
5.1. The rights granted under this License will terminate automatically if You fail to comply with any of its terms. However, if You become compliant, then the rights granted under this License from a particular Contributor are reinstated (a) provisionally, unless and until such Contributor explicitly and finally terminates Your grants, and (b) on an ongoing basis, if such Contributor fails to notify You of the non-compliance by some reasonable means prior to 60 days after You have come back into compliance. Moreover, Your grants from a particular Contributor are reinstated on an ongoing basis if such Contributor notifies You of the non-compliance by some reasonable means, this is the first time You have received notice of non-compliance with this License from such Contributor, and You become compliant prior to 30 days after Your receipt of the notice.
175 |
5.2. If You initiate litigation against any entity by asserting a patent infringement claim (excluding declaratory judgment actions, counter-claims, and cross-claims) alleging that a Contributor Version directly or indirectly infringes any patent, then the rights granted to You by any and all Contributors for the Covered Software under Section 2.1 of this License shall terminate.
176 |
5.3. In the event of termination under Sections 5.1 or 5.2 above, all end user license agreements (excluding distributors and resellers) which have been validly granted by You or Your distributors under this License prior to termination shall survive termination.
177 |
6. Disclaimer of Warranty
178 |
Covered Software is provided under this License on an “as is” basis, without warranty of any kind, either expressed, implied, or statutory, including, without limitation, warranties that the Covered Software is free of defects, merchantable, fit for a particular purpose or non-infringing. The entire risk as to the quality and performance of the Covered Software is with You. Should any Covered Software prove defective in any respect, You (not any Contributor) assume the cost of any necessary servicing, repair, or correction. This disclaimer of warranty constitutes an essential part of this License. No use of any Covered Software is authorized under this License except under this disclaimer.
179 |
7. Limitation of Liability
180 |
Under no circumstances and under no legal theory, whether tort (including negligence), contract, or otherwise, shall any Contributor, or anyone who distributes Covered Software as permitted above, be liable to You for any direct, indirect, special, incidental, or consequential damages of any character including, without limitation, damages for lost profits, loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses, even if such party shall have been informed of the possibility of such damages. This limitation of liability shall not apply to liability for death or personal injury resulting from such party’s negligence to the extent applicable law prohibits such limitation. Some jurisdictions do not allow the exclusion or limitation of incidental or consequential damages, so this exclusion and limitation may not apply to You.
181 |
8. Litigation
182 |
Any litigation relating to this License may be brought only in the courts of a jurisdiction where the defendant maintains its principal place of business and such litigation shall be governed by laws of that jurisdiction, without reference to its conflict-of-law provisions. Nothing in this Section shall prevent a party’s ability to bring cross-claims or counter-claims.
183 |
9. Miscellaneous
184 |
This License represents the complete agreement concerning the subject matter hereof. If any provision of this License is held to be unenforceable, such provision shall be reformed only to the extent necessary to make it enforceable. Any law or regulation which provides that the language of a contract shall be construed against the drafter shall not be used to construe this License against a Contributor.
185 |
10. Versions of the License
186 |
10.1. New Versions
187 |
Mozilla Foundation is the license steward. Except as provided in Section 10.3, no one other than the license steward has the right to modify or publish new versions of this License. Each version will be given a distinguishing version number.
188 |
10.2. Effect of New Versions
189 |
You may distribute the Covered Software under the terms of the version of the License under which You originally received the Covered Software, or under the terms of any subsequent version published by the license steward.
190 |
10.3. Modified Versions
191 |
If you create software not governed by this License, and you want to create a new license for such software, you may create and use a modified version of this License if you rename the license and remove any references to the name of the license steward (except to note that such modified license differs from this License).
192 |
10.4. Distributing Source Code Form that is Incompatible With Secondary Licenses
193 |
If You choose to distribute Source Code Form that is Incompatible With Secondary Licenses under the terms of this version of the License, the notice described in Exhibit B of this License must be attached.
194 |
Exhibit A - Source Code Form License Notice
195 |
196 |
This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
197 |
198 |
If it is not possible or desirable to put the notice in a particular file, then You may include the notice in a location (such as a LICENSE file in a relevant directory) where a recipient would be likely to look for such a notice.
199 |
You may add additional accurate notices of copyright ownership.
200 |
Exhibit B - “Incompatible With Secondary Licenses” Notice
201 |
202 |
This Source Code Form is “Incompatible With Secondary Licenses”, as defined by the Mozilla Public License, v. 2.0.
203 |
204 |
205 |
206 |
--------------------------------------------------------------------------------
/MarkdownTools.sublime-project:
--------------------------------------------------------------------------------
1 | {
2 | "folders":
3 | [
4 | {
5 | "name": "MarkdownTools",
6 | "path": ".",
7 | "folder_exclude_patterns": ["__pycache__", "venv27", "venv33", "venv34", ".git"]
8 | }
9 | ]
10 | }
11 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # MarkdownTools
2 |
3 | MarkdownTools is a collection of command line utilities for processing Markdown text files. At the moment the collection includes only one utility: **mdmerge**. Over time additional utilities will be added to support Markdown workflows.
4 |
5 | Current stable version is 1.0. See the *Installation* section below for guidance.
6 |
7 | ## mdmerge
8 |
9 | mdmerge is a command line utility that produces a single Markdown document by merging a set of Markdown documents. The merge can be accomplished by expanding *include specifications* found in the input files, by concatenating a list of files found in an index file, or both.
10 |
11 | ### Synergy with Marked
12 |
13 | Brett Terpstra's [Marked 2][] application is a GUI product that runs on OS X; it watches Markdown text files and displays the formatted output; it has extensive support for multi-file Markdown documents. *Marked* is my tool of choice for viewing formatted Markdown. I use it whenever I'm creating or reviewing Markdown content on my OS X machine. The invaluable multi-file document support in *Marked* is what drove me to create **mdmerge**.
14 |
15 | [Marked 2]: http://marked2app.com
16 |
17 | **mdmerge** brings that same multi-file Markdown document processing to the command line. It is useful in any automated scripting environment where Markdown is processed. For example, I use it in automated build scripts (e.g., using gmake or Grunt) to produce documentation for the software I'm building. It is cross-platform; you can pre-process the Markdown files on any common OS that has a recent version of Python.
18 |
19 | ### Markdown and include file syntax support
20 |
21 | mdmerge has been tested with documents containing these Markdown syntax variants:
22 |
23 | * classic ([John Gruber's Markdown syntax][gruber])
24 | * MultiMarkdown (Fletcher Penny's syntax, [MultiMarkdown][mmd] version 4)
25 | * [GHF][ghf] (GitHub Flavored Markdown)
26 |
27 | [gruber]: http://daringfireball.net/projects/markdown/syntax
28 | [mmd]: http://fletcherpenney.net/multimarkdown/
29 | [ghf]: https://help.github.com/articles/github-flavored-markdown
30 |
31 | mdmerge accepts include declarations in these styles
32 |
33 | * [MultiMarkdown transclusion][mmdtrans]
34 | * [Marked file includes][terpstramf]
35 | * [LeanPub code includes][leanpubcd] (as [interpreted by Marked][terpstracd])
36 | * [LeanPub index files][leanpubidx]
37 | * [mmd_merge index files][mmdidx]
38 |
39 | [terpstramf]: http://marked2app.com/help/Multi-File_Documents.html
40 | [terpstracd]: http://marked2app.com/help/Special_Syntax.html#includingcode
41 | [leanpubcd]: https://leanpub.com/help/manual#leanpub-auto-code
42 | [leanpubidx]: https://leanpub.com/help/manual#leanpub-auto-the-booktxt-file
43 | [mmdtrans]: http://fletcher.github.io/MultiMarkdown-4/transclusion
44 | [mmdidx]: https://github.com/fletcher/MMD-Support/blob/master/Utilities/mmd_merge.pl
45 |
46 | Includes can be nested; that is, a file can include another file that itself include other files, and so on. Index (or book) files are only processed as such when they are the primary input; they cannot be nested -- but the files listed in the index file are treated as normal input files (expanding include specifications found within).
47 |
48 | ## some examples
49 |
50 | This example shows an include specification of another markdown file:
51 |
52 |
This next bit is an included Markdown file. If it also has embedded include specifications, they will be processed as well; these kinds of includes are nested.
53 |
54 | <<[section-a.md]
55 |
56 | End of example.
57 |
58 | This example shows an include specification for source code:
59 |
60 |
This next bit is included source code. It is not examined for nested include specifications.
61 |
62 | <<(example.c)
63 |
64 | End of example.
65 |
66 | This example shows a normal MultiMarkdown transclusion and a source code transclusion:
67 |
68 |
This demonstrates MultiMarkdown transclusions:
69 |
70 | {{section-a.mmd}}
71 |
72 | ```C
73 | {{example.c}}
74 | ```
75 |
76 | End of example.
77 |
78 | And of course there are raw file includes (`<<{raw.html}`) and index files. Read the documentation linked in the previous section or look at `docs/specifications.mmd` in the `master` branch.
79 |
80 | ## Installation
81 |
82 | Installation packages are available on PyPI. For Python 3 (3.3 or later) install the `MarkdownTools`; for Python 2 (2.6 or later) install the `MarkdownTools2` package.
83 |
84 | Install the package using pip, like this (in a Python 3 environment):
85 |
86 | ~~~bash
87 | $ pip install MarkdownTools
88 | ~~~
89 |
90 | or (in a Python 2 environment):
91 |
92 | ~~~bash
93 | $ pip install MarkdownTools2
94 | ~~~
95 |
96 | If you are upgrading an existing version, use `pip install --upgrade`.
97 |
98 | You may need to use `sudo` if you are installing into the system's native Python environment.
99 |
100 | ## Usage
101 |
102 | The command line looks like this:
103 |
104 | mdmerge [options] [-o outputfile] inputfile [inputFile ...]
105 | mdmerge [options] [-o outputfile] -
106 |
107 | ### Command arguments
108 |
109 | options
110 | : One or more of `--book`, `--export-target`, `-h`, `--help`, `--ignore-transclusions`, `--just-raw` `--leanpub`, `--version`.
111 |
112 | `--book`
113 | : Treat STDIN as an index file (a "book" file).
114 |
115 | `--export-target [html|latex|lyx|opml|rtf|odf]`
116 | : Indicates the ultimate output target of the markdown processor, but primarily impacts wildcard substitution in Marked inclusion.
117 |
118 | `-h`
119 | : Help information
120 |
121 | `--help`
122 | : Same as `-h`.
123 |
124 | `--ignore-transclusions`
125 | : Leave any MultiMarkdown transclusion specifications alone; do not include
126 | the specified file. Useful if you want to mix Marked/LeanPub includes and
127 | MultiMarkdown includes, but have MultiMarkdown handline the transclusions.
128 |
129 | `--just-raw`
130 | : Ignore all include specifications except for raw includes; useful for
131 | processing the output of the Markdown processor to pick up the raw file include
132 | specifications that should have passed through untouched.
133 |
134 | `--leanpub`
135 | : Indicates that any input file named `book.txt` should be treated as a LeanPub index file.
136 |
137 | `--version`
138 | : Gives the version information about the utility.
139 |
140 | `-o outputfile`
141 | : The filepath in which to store the merged text. If not specified, then STDOUT is used.
142 |
143 | `--outfile outputfile`
144 | : same as `-o`.
145 |
146 | `-`
147 | : The input comes from STDIN.
148 |
149 | `inputfile`
150 | : A list of space separated input files that can be merged together. If multiple files are given, they are treated as if they were specified in a LeanPub index file.
151 |
152 | ## Development
153 |
154 | MarkdownTools are written in Python. The project repository contains `python2/*` branches that target Python 2 (2.6 and later) and `python3/*` branches that target Python 3 (3.3 and later). There are unit tests on each branch that can be executed using the `runtests` command script.
155 |
156 | The `master` branch does not contain any source or tests; it contains the README file and a few other files that describe aspects of the project.
157 |
158 | ## Testing
159 |
160 | To run the tests:
161 |
162 | ~~~bash
163 | $ ./runtests.sh
164 | ~~~
165 |
166 | For Python 2 environments you will need to install the *mock* package (e.g., `pip install mock`).
167 |
168 | ## Contributing
169 |
170 | Similar to the contribution guidance from :
171 |
172 | 1. Fork it.
173 | 1. Create a branch (`git checkout -b my_MarkdownTools`)
174 | 1. Commit your changes (`git commit -am "Added Snarkdown"`)
175 | 1. Push to the branch (`git push origin my_MarkdownTools`)
176 | 1. Open a [Pull Request](http://github.com/jenesuispasdave/MarkdownTools/pulls)
177 | 1. Enjoy a refreshing beverage and wait
178 |
179 | Contributors should read the **developer documentation**, available in the `docs` directory of the `master` branch. To produce a nice pretty HTML version of those docs, install the doc tools (see the `docs-support` directory) and run the `make-docs` script in the `docs` directroy.
180 |
181 | ## License and Copyright
182 |
183 | MarkdownTools is licensed with the [Mozilla Public License Version 2.0][mpl].
184 |
185 | Copyright 2014 Dave Hein
186 |
187 | [mpl]: http://www.mozilla.org/MPL/2.0/
188 |
--------------------------------------------------------------------------------
/docs-support/.gitignore:
--------------------------------------------------------------------------------
1 | .sass-cache/
2 | .ruby-version
3 |
--------------------------------------------------------------------------------
/docs-support/config.rb:
--------------------------------------------------------------------------------
1 | # Require any additional compass plugins here.
2 |
3 | # Set this to the root of your project when deployed:
4 | http_path = "/"
5 | css_dir = "css"
6 | sass_dir = "sass"
7 | images_dir = "images"
8 | javascripts_dir = "js"
9 |
10 | # You can select your preferred output style here (can be overridden via the command line):
11 | # output_style = :expanded or :nested or :compact or :compressed
12 | output_style = :expanded
13 |
14 | # To enable relative paths to assets via compass helper functions. Uncomment:
15 | # relative_assets = true
16 |
17 | # To disable debugging comments that display the original location of your selectors. Uncomment:
18 | # line_comments = false
19 | line_comments = false
20 |
21 |
22 | # If you prefer the indented syntax, you might want to regenerate this
23 | # project again passing --syntax sass, or you can uncomment this:
24 | # preferred_syntax = :sass
25 | # and then run:
26 | # sass-convert -R --from scss --to sass sass scss && rm -rf sass && mv scss sass
27 |
--------------------------------------------------------------------------------
/docs-support/css/ie.css:
--------------------------------------------------------------------------------
1 | /* Welcome to Compass. Use this file to write IE specific override styles.
2 | * Import this file using the following HTML or equivalent:
3 | * */
6 |
--------------------------------------------------------------------------------
/docs-support/css/print.css:
--------------------------------------------------------------------------------
1 | /* Welcome to Compass. Use this file to define print styles.
2 | * Import this file using the following HTML or equivalent:
3 | * */
4 | html, body, div, span, applet, object, iframe,
5 | h1, h2, h3, h4, h5, h6, p, blockquote, pre,
6 | a, abbr, acronym, address, big, cite, code,
7 | del, dfn, em, img, ins, kbd, q, s, samp,
8 | small, strike, strong, sub, sup, tt, var,
9 | b, u, i, center,
10 | dl, dt, dd, ol, ul, li,
11 | fieldset, form, label, legend,
12 | table, caption, tbody, tfoot, thead, tr, th, td,
13 | article, aside, canvas, details, embed,
14 | figure, figcaption, footer, header, hgroup,
15 | menu, nav, output, ruby, section, summary,
16 | time, mark, audio, video {
17 | margin: 0;
18 | padding: 0;
19 | border: 0;
20 | font: inherit;
21 | font-size: 100%;
22 | vertical-align: baseline;
23 | }
24 |
25 | html {
26 | line-height: 1;
27 | }
28 |
29 | ol, ul {
30 | list-style: none;
31 | }
32 |
33 | table {
34 | border-collapse: collapse;
35 | border-spacing: 0;
36 | }
37 |
38 | caption, th, td {
39 | text-align: left;
40 | font-weight: normal;
41 | vertical-align: middle;
42 | }
43 |
44 | q, blockquote {
45 | quotes: none;
46 | }
47 | q:before, q:after, blockquote:before, blockquote:after {
48 | content: "";
49 | content: none;
50 | }
51 |
52 | a img {
53 | border: none;
54 | }
55 |
56 | article, aside, details, figcaption, figure, footer, header, hgroup, menu, nav, section, summary {
57 | display: block;
58 | }
59 |
60 | *, *:after, *:before {
61 | -webkit-box-sizing: border-box;
62 | -moz-box-sizing: border-box;
63 | box-sizing: border-box;
64 | }
65 |
66 | body {
67 | font-size: 12px;
68 | }
69 |
70 | body {
71 | padding: 1em;
72 | font-family: Verdana, Tahoma, sans-serif;
73 | font-weight: 400;
74 | line-height: 1.4em;
75 | }
76 |
77 | p {
78 | padding-top: 0.5em;
79 | padding-bottom: 0.5em;
80 | }
81 |
82 | h1, h2, h3, h4, h5, h6 {
83 | font-family: Baskerville, Garamond, Palatino, "Palatino Linotype", "Hoefler Text", "Times New Roman", serif;
84 | font-weight: 600;
85 | margin-bottom: 0.5em;
86 | margin-top: 0.5em;
87 | padding-top: 0.5em;
88 | padding-bottom: 0.25em;
89 | }
90 |
91 | h1 {
92 | font-size: 1.728em;
93 | border-bottom-color: black;
94 | border-bottom-style: double;
95 | border-bottom-width: thick;
96 | }
97 |
98 | h2 {
99 | font-size: 1.44em;
100 | border-bottom-color: black;
101 | border-bottom-style: solid;
102 | border-bottom-width: thin;
103 | }
104 |
105 | h3 {
106 | font-size: 1.2em;
107 | }
108 |
109 | h4 {
110 | font-size: 1em;
111 | }
112 |
113 | em {
114 | font-style: italic;
115 | }
116 |
117 | strong {
118 | font-weight: 600;
119 | }
120 |
121 | code {
122 | font-family: "Source Code Pro", Consolas, "Bitstream Vera Sans Mono", "Andale Mono", Monaco, "DejaVu Sans Mono", "Lucida Console", monospace;
123 | font-weight: 400;
124 | }
125 |
126 | pre code {
127 | white-space: pre-wrap;
128 | }
129 |
130 | pre {
131 | background: whitesmoke;
132 | margin-left: 1em;
133 | margin-right: 1em;
134 | padding: 0.25em;
135 | display: inline-block;
136 | display: block;
137 | overflow: visible;
138 | word-break: normal;
139 | width: 96.66667%;
140 | min-width: 24.5em;
141 | }
142 |
143 | blockquote {
144 | margin-top: 1em;
145 | margin-bottom: 1em;
146 | margin-left: 2em;
147 | font-style: italic;
148 | }
149 |
150 | table {
151 | border: 1px solid rgba(0, 0, 0, 0.25);
152 | border-collapse: collapse;
153 | display: table;
154 | empty-cells: hide;
155 | table-layout: fixed;
156 | font-size: 0.75em;
157 | }
158 |
159 | caption {
160 | display: table-caption;
161 | font-weight: 700;
162 | }
163 |
164 | col {
165 | display: table-column;
166 | }
167 |
168 | colgroup {
169 | display: table-column-group;
170 | }
171 |
172 | tbody {
173 | display: table-row-group;
174 | }
175 |
176 | tfoot {
177 | display: table-footer-group;
178 | }
179 |
180 | thead {
181 | display: table-header-group;
182 | }
183 |
184 | td, th {
185 | display: table-cell;
186 | padding: 0.25em;
187 | }
188 |
189 | tr {
190 | display: table-row;
191 | }
192 |
193 | th {
194 | font-weight: 600;
195 | }
196 |
197 | table thead {
198 | background: rgba(0, 0, 0, 0.15);
199 | border: 1px solid rgba(0, 0, 0, 0.15);
200 | border-bottom: 1px solid rgba(0, 0, 0, 0.2);
201 | }
202 |
203 | table tbody {
204 | background: rgba(0, 0, 0, 0.05);
205 | }
206 |
207 | table tfoot {
208 | background: rgba(0, 0, 0, 0.15);
209 | border: 1px solid rgba(0, 0, 0, 0.15);
210 | border-top: 1px solid rgba(0, 0, 0, 0.2);
211 | }
212 |
213 | table tr:nth-child(odd), table th:nth-child(odd), table td:nth-child(odd) {
214 | background: rgba(255, 255, 255, 0.06);
215 | }
216 |
217 | table tr:nth-child(even), table td:nth-child(even) {
218 | background: rgba(200, 200, 200, 0.25);
219 | }
220 |
221 | sup {
222 | font-size: .75em;
223 | line-height: 0.46667em;
224 | vertical-align: baseline;
225 | position: relative;
226 | top: -0.46667em;
227 | }
228 |
229 | sub {
230 | font-size: .75em;
231 | line-height: 0.46667em;
232 | vertical-align: baseline;
233 | position: relative;
234 | top: 0.46667em;
235 | }
236 |
237 | ul {
238 | list-style-type: disc;
239 | list-style-position: outside;
240 | padding-left: 2em;
241 | }
242 | ul ul {
243 | list-style-type: circle;
244 | padding-left: 2em;
245 | }
246 | ul ul ul {
247 | list-style-type: square;
248 | padding-left: 2em;
249 | }
250 |
251 | ol {
252 | list-style-type: decimal;
253 | list-style-position: outside;
254 | padding-left: 2em;
255 | }
256 | ol ol {
257 | list-style-type: lower-alpha;
258 | padding-left: 2em;
259 | }
260 | ol ol ol {
261 | list-style-type: lower-roman;
262 | padding-left: 2em;
263 | }
264 |
265 | dt {
266 | font-weight: 600;
267 | }
268 |
269 | dd {
270 | padding-left: 2em;
271 | padding-top: 0.25em;
272 | padding-bottom: 0.25em;
273 | }
274 |
275 | a.backref {
276 | text-decoration: none;
277 | }
278 |
279 | body {
280 | margin-left: 0em;
281 | margin-right: auto;
282 | max-width: 60em;
283 | min-width: 30em;
284 | }
285 |
286 | .backref {
287 | font-size: 2rem;
288 | float: right;
289 | }
290 |
291 | a.backref {
292 | display: none;
293 | }
294 |
--------------------------------------------------------------------------------
/docs-support/css/screen.css:
--------------------------------------------------------------------------------
1 | html, body, div, span, applet, object, iframe,
2 | h1, h2, h3, h4, h5, h6, p, blockquote, pre,
3 | a, abbr, acronym, address, big, cite, code,
4 | del, dfn, em, img, ins, kbd, q, s, samp,
5 | small, strike, strong, sub, sup, tt, var,
6 | b, u, i, center,
7 | dl, dt, dd, ol, ul, li,
8 | fieldset, form, label, legend,
9 | table, caption, tbody, tfoot, thead, tr, th, td,
10 | article, aside, canvas, details, embed,
11 | figure, figcaption, footer, header, hgroup,
12 | menu, nav, output, ruby, section, summary,
13 | time, mark, audio, video {
14 | margin: 0;
15 | padding: 0;
16 | border: 0;
17 | font: inherit;
18 | font-size: 100%;
19 | vertical-align: baseline;
20 | }
21 |
22 | html {
23 | line-height: 1;
24 | }
25 |
26 | ol, ul {
27 | list-style: none;
28 | }
29 |
30 | table {
31 | border-collapse: collapse;
32 | border-spacing: 0;
33 | }
34 |
35 | caption, th, td {
36 | text-align: left;
37 | font-weight: normal;
38 | vertical-align: middle;
39 | }
40 |
41 | q, blockquote {
42 | quotes: none;
43 | }
44 | q:before, q:after, blockquote:before, blockquote:after {
45 | content: "";
46 | content: none;
47 | }
48 |
49 | a img {
50 | border: none;
51 | }
52 |
53 | article, aside, details, figcaption, figure, footer, header, hgroup, menu, nav, section, summary {
54 | display: block;
55 | }
56 |
57 | *, *:after, *:before {
58 | -webkit-box-sizing: border-box;
59 | -moz-box-sizing: border-box;
60 | box-sizing: border-box;
61 | }
62 |
63 | body {
64 | font-size: 19.2px;
65 | }
66 |
67 | body {
68 | padding: 1em;
69 | font-family: "Lucida Grande", "Lucida Sans Unicode", "Lucida Sans", Verdana, Tahoma, sans-serif;
70 | font-weight: 400;
71 | line-height: 1.4em;
72 | }
73 |
74 | p {
75 | padding-top: 0.5em;
76 | padding-bottom: 0.5em;
77 | }
78 |
79 | h1, h2, h3, h4, h5, h6 {
80 | font-family: Baskerville, Garamond, Palatino, "Palatino Linotype", "Hoefler Text", "Times New Roman", serif;
81 | font-weight: 600;
82 | margin-bottom: 0.5em;
83 | margin-top: 0.5em;
84 | padding-top: 0.5em;
85 | padding-bottom: 0.25em;
86 | }
87 |
88 | h1 {
89 | font-size: 1.728em;
90 | border-bottom-color: black;
91 | border-bottom-style: double;
92 | border-bottom-width: thick;
93 | }
94 |
95 | h2 {
96 | font-size: 1.44em;
97 | border-bottom-color: black;
98 | border-bottom-style: solid;
99 | border-bottom-width: thin;
100 | }
101 |
102 | h3 {
103 | font-size: 1.2em;
104 | }
105 |
106 | h4 {
107 | font-size: 1em;
108 | }
109 |
110 | em {
111 | font-style: italic;
112 | }
113 |
114 | strong {
115 | font-weight: 600;
116 | }
117 |
118 | code {
119 | font-family: "Source Code Pro", Consolas, "Bitstream Vera Sans Mono", "Andale Mono", Monaco, "DejaVu Sans Mono", "Lucida Console", monospace;
120 | font-weight: 400;
121 | }
122 |
123 | pre {
124 | background: whitesmoke;
125 | margin-left: 1em;
126 | margin-right: 1em;
127 | padding: 0.25em;
128 | display: inline-block;
129 | overflow: auto;
130 | width: 96.66667%;
131 | min-width: 24.5em;
132 | }
133 |
134 | blockquote {
135 | margin-top: 1em;
136 | margin-bottom: 1em;
137 | margin-left: 2em;
138 | font-style: italic;
139 | }
140 |
141 | table {
142 | border: 1px solid rgba(0, 0, 0, 0.25);
143 | border-collapse: collapse;
144 | display: table;
145 | empty-cells: hide;
146 | table-layout: fixed;
147 | font-size: 0.75em;
148 | }
149 |
150 | caption {
151 | display: table-caption;
152 | font-weight: 700;
153 | }
154 |
155 | col {
156 | display: table-column;
157 | }
158 |
159 | colgroup {
160 | display: table-column-group;
161 | }
162 |
163 | tbody {
164 | display: table-row-group;
165 | }
166 |
167 | tfoot {
168 | display: table-footer-group;
169 | }
170 |
171 | thead {
172 | display: table-header-group;
173 | }
174 |
175 | td, th {
176 | display: table-cell;
177 | padding: 0.25em;
178 | }
179 |
180 | tr {
181 | display: table-row;
182 | }
183 |
184 | th {
185 | font-weight: 600;
186 | }
187 |
188 | table thead {
189 | background: rgba(0, 0, 0, 0.15);
190 | border: 1px solid rgba(0, 0, 0, 0.15);
191 | border-bottom: 1px solid rgba(0, 0, 0, 0.2);
192 | }
193 |
194 | table tbody {
195 | background: rgba(0, 0, 0, 0.05);
196 | }
197 |
198 | table tfoot {
199 | background: rgba(0, 0, 0, 0.15);
200 | border: 1px solid rgba(0, 0, 0, 0.15);
201 | border-top: 1px solid rgba(0, 0, 0, 0.2);
202 | }
203 |
204 | table tr:nth-child(odd), table th:nth-child(odd), table td:nth-child(odd) {
205 | background: rgba(255, 255, 255, 0.06);
206 | }
207 |
208 | table tr:nth-child(even), table td:nth-child(even) {
209 | background: rgba(200, 200, 200, 0.25);
210 | }
211 |
212 | sup {
213 | font-size: .75em;
214 | line-height: 0.46667em;
215 | vertical-align: baseline;
216 | position: relative;
217 | top: -0.46667em;
218 | }
219 |
220 | sub {
221 | font-size: .75em;
222 | line-height: 0.46667em;
223 | vertical-align: baseline;
224 | position: relative;
225 | top: 0.46667em;
226 | }
227 |
228 | ul {
229 | list-style-type: disc;
230 | list-style-position: outside;
231 | padding-left: 2em;
232 | }
233 | ul ul {
234 | list-style-type: circle;
235 | padding-left: 2em;
236 | }
237 | ul ul ul {
238 | list-style-type: square;
239 | padding-left: 2em;
240 | }
241 |
242 | ol {
243 | list-style-type: decimal;
244 | list-style-position: outside;
245 | padding-left: 2em;
246 | }
247 | ol ol {
248 | list-style-type: lower-alpha;
249 | padding-left: 2em;
250 | }
251 | ol ol ol {
252 | list-style-type: lower-roman;
253 | padding-left: 2em;
254 | }
255 |
256 | dt {
257 | font-weight: 600;
258 | }
259 |
260 | dd {
261 | padding-left: 2em;
262 | padding-top: 0.25em;
263 | padding-bottom: 0.25em;
264 | }
265 |
266 | a.backref {
267 | text-decoration: none;
268 | }
269 |
270 | body {
271 | margin-left: auto;
272 | margin-right: auto;
273 | max-width: 60em;
274 | min-width: 30em;
275 | }
276 |
277 | .backref {
278 | font-size: 2rem;
279 | float: right;
280 | }
281 |
--------------------------------------------------------------------------------
/docs-support/js/highlight.pack.js:
--------------------------------------------------------------------------------
1 | var hljs=new function(){function k(v){return v.replace(/&/gm,"&").replace(//gm,">")}function t(v){return v.nodeName.toLowerCase()}function i(w,x){var v=w&&w.exec(x);return v&&v.index==0}function d(v){return Array.prototype.map.call(v.childNodes,function(w){if(w.nodeType==3){return b.useBR?w.nodeValue.replace(/\n/g,""):w.nodeValue}if(t(w)=="br"){return"\n"}return d(w)}).join("")}function r(w){var v=(w.className+" "+(w.parentNode?w.parentNode.className:"")).split(/\s+/);v=v.map(function(x){return x.replace(/^language-/,"")});return v.filter(function(x){return j(x)||x=="no-highlight"})[0]}function o(x,y){var v={};for(var w in x){v[w]=x[w]}if(y){for(var w in y){v[w]=y[w]}}return v}function u(x){var v=[];(function w(y,z){for(var A=y.firstChild;A;A=A.nextSibling){if(A.nodeType==3){z+=A.nodeValue.length}else{if(t(A)=="br"){z+=1}else{if(A.nodeType==1){v.push({event:"start",offset:z,node:A});z=w(A,z);v.push({event:"stop",offset:z,node:A})}}}}return z})(x,0);return v}function q(w,y,C){var x=0;var F="";var z=[];function B(){if(!w.length||!y.length){return w.length?w:y}if(w[0].offset!=y[0].offset){return(w[0].offset"}function E(G){F+=""+t(G)+">"}function v(G){(G.event=="start"?A:E)(G.node)}while(w.length||y.length){var D=B();F+=k(C.substr(x,D[0].offset-x));x=D[0].offset;if(D==w){z.reverse().forEach(E);do{v(D.splice(0,1)[0]);D=B()}while(D==w&&D.length&&D[0].offset==x);z.reverse().forEach(A)}else{if(D[0].event=="start"){z.push(D[0].node)}else{z.pop()}v(D.splice(0,1)[0])}}return F+k(C.substr(x))}function m(y){function v(z){return(z&&z.source)||z}function w(A,z){return RegExp(v(A),"m"+(y.cI?"i":"")+(z?"g":""))}function x(D,C){if(D.compiled){return}D.compiled=true;D.k=D.k||D.bK;if(D.k){var z={};function E(G,F){if(y.cI){F=F.toLowerCase()}F.split(" ").forEach(function(H){var I=H.split("|");z[I[0]]=[G,I[1]?Number(I[1]):1]})}if(typeof D.k=="string"){E("keyword",D.k)}else{Object.keys(D.k).forEach(function(F){E(F,D.k[F])})}D.k=z}D.lR=w(D.l||/\b[A-Za-z0-9_]+\b/,true);if(C){if(D.bK){D.b=D.bK.split(" ").join("|")}if(!D.b){D.b=/\B|\b/}D.bR=w(D.b);if(!D.e&&!D.eW){D.e=/\B|\b/}if(D.e){D.eR=w(D.e)}D.tE=v(D.e)||"";if(D.eW&&C.tE){D.tE+=(D.e?"|":"")+C.tE}}if(D.i){D.iR=w(D.i)}if(D.r===undefined){D.r=1}if(!D.c){D.c=[]}var B=[];D.c.forEach(function(F){if(F.v){F.v.forEach(function(G){B.push(o(F,G))})}else{B.push(F=="self"?D:F)}});D.c=B;D.c.forEach(function(F){x(F,D)});if(D.starts){x(D.starts,C)}var A=D.c.map(function(F){return F.bK?"\\.?\\b("+F.b+")\\b\\.?":F.b}).concat([D.tE]).concat([D.i]).map(v).filter(Boolean);D.t=A.length?w(A.join("|"),true):{exec:function(F){return null}};D.continuation={}}x(y)}function c(S,L,J,R){function v(U,V){for(var T=0;T";U+=Z+'">';return U+X+Y}function N(){var U=k(C);if(!I.k){return U}var T="";var X=0;I.lR.lastIndex=0;var V=I.lR.exec(U);while(V){T+=U.substr(X,V.index-X);var W=E(I,V);if(W){H+=W[1];T+=w(W[0],V[0])}else{T+=V[0]}X=I.lR.lastIndex;V=I.lR.exec(U)}return T+U.substr(X)}function F(){if(I.sL&&!f[I.sL]){return k(C)}var T=I.sL?c(I.sL,C,true,I.continuation.top):g(C);if(I.r>0){H+=T.r}if(I.subLanguageMode=="continuous"){I.continuation.top=T.top}return w(T.language,T.value,false,true)}function Q(){return I.sL!==undefined?F():N()}function P(V,U){var T=V.cN?w(V.cN,"",true):"";if(V.rB){D+=T;C=""}else{if(V.eB){D+=k(U)+T;C=""}else{D+=T;C=U}}I=Object.create(V,{parent:{value:I}})}function G(T,X){C+=T;if(X===undefined){D+=Q();return 0}var V=v(X,I);if(V){D+=Q();P(V,X);return V.rB?0:X.length}var W=z(I,X);if(W){var U=I;if(!(U.rE||U.eE)){C+=X}D+=Q();do{if(I.cN){D+=""}H+=I.r;I=I.parent}while(I!=W.parent);if(U.eE){D+=k(X)}C="";if(W.starts){P(W.starts,"")}return U.rE?0:X.length}if(A(X,I)){throw new Error('Illegal lexeme "'+X+'" for mode "'+(I.cN||"")+'"')}C+=X;return X.length||1}var M=j(S);if(!M){throw new Error('Unknown language: "'+S+'"')}m(M);var I=R||M;var D="";for(var K=I;K!=M;K=K.parent){if(K.cN){D=w(K.cN,D,true)}}var C="";var H=0;try{var B,y,x=0;while(true){I.t.lastIndex=x;B=I.t.exec(L);if(!B){break}y=G(L.substr(x,B.index-x),B[0]);x=B.index+y}G(L.substr(x));for(var K=I;K.parent;K=K.parent){if(K.cN){D+=""}}return{r:H,value:D,language:S,top:I}}catch(O){if(O.message.indexOf("Illegal")!=-1){return{r:0,value:k(L)}}else{throw O}}}function g(y,x){x=x||b.languages||Object.keys(f);var v={r:0,value:k(y)};var w=v;x.forEach(function(z){if(!j(z)){return}var A=c(z,y,false);A.language=z;if(A.r>w.r){w=A}if(A.r>v.r){w=v;v=A}});if(w.language){v.second_best=w}return v}function h(v){if(b.tabReplace){v=v.replace(/^((<[^>]+>|\t)+)/gm,function(w,z,y,x){return z.replace(/\t/g,b.tabReplace)})}if(b.useBR){v=v.replace(/\n/g," ")}return v}function p(z){var y=d(z);var A=r(z);if(A=="no-highlight"){return}var v=A?c(A,y,true):g(y);var w=u(z);if(w.length){var x=document.createElementNS("http://www.w3.org/1999/xhtml","pre");x.innerHTML=v.value;v.value=q(w,u(x),y)}v.value=h(v.value);z.innerHTML=v.value;z.className+=" hljs "+(!A&&v.language||"");z.result={language:v.language,re:v.r};if(v.second_best){z.second_best={language:v.second_best.language,re:v.second_best.r}}}var b={classPrefix:"hljs-",tabReplace:null,useBR:false,languages:undefined};function s(v){b=o(b,v)}function l(){if(l.called){return}l.called=true;var v=document.querySelectorAll("pre code");Array.prototype.forEach.call(v,p)}function a(){addEventListener("DOMContentLoaded",l,false);addEventListener("load",l,false)}var f={};var n={};function e(v,x){var w=f[v]=x(this);if(w.aliases){w.aliases.forEach(function(y){n[y]=v})}}function j(v){return f[v]||f[n[v]]}this.highlight=c;this.highlightAuto=g;this.fixMarkup=h;this.highlightBlock=p;this.configure=s;this.initHighlighting=l;this.initHighlightingOnLoad=a;this.registerLanguage=e;this.getLanguage=j;this.inherit=o;this.IR="[a-zA-Z][a-zA-Z0-9_]*";this.UIR="[a-zA-Z_][a-zA-Z0-9_]*";this.NR="\\b\\d+(\\.\\d+)?";this.CNR="(\\b0[xX][a-fA-F0-9]+|(\\b\\d+(\\.\\d*)?|\\.\\d+)([eE][-+]?\\d+)?)";this.BNR="\\b(0b[01]+)";this.RSR="!|!=|!==|%|%=|&|&&|&=|\\*|\\*=|\\+|\\+=|,|-|-=|/=|/|:|;|<<|<<=|<=|<|===|==|=|>>>=|>>=|>=|>>>|>>|>|\\?|\\[|\\{|\\(|\\^|\\^=|\\||\\|=|\\|\\||~";this.BE={b:"\\\\[\\s\\S]",r:0};this.ASM={cN:"string",b:"'",e:"'",i:"\\n",c:[this.BE]};this.QSM={cN:"string",b:'"',e:'"',i:"\\n",c:[this.BE]};this.CLCM={cN:"comment",b:"//",e:"$"};this.CBLCLM={cN:"comment",b:"/\\*",e:"\\*/"};this.HCM={cN:"comment",b:"#",e:"$"};this.NM={cN:"number",b:this.NR,r:0};this.CNM={cN:"number",b:this.CNR,r:0};this.BNM={cN:"number",b:this.BNR,r:0};this.REGEXP_MODE={cN:"regexp",b:/\//,e:/\/[gim]*/,i:/\n/,c:[this.BE,{b:/\[/,e:/\]/,r:0,c:[this.BE]}]};this.TM={cN:"title",b:this.IR,r:0};this.UTM={cN:"title",b:this.UIR,r:0}}();hljs.registerLanguage("cs",function(b){var a="abstract as base bool break byte case catch char checked const continue decimal default delegate do double else enum event explicit extern false finally fixed float for foreach goto if implicit in int interface internal is lock long new null object operator out override params private protected public readonly ref return sbyte sealed short sizeof stackalloc static string struct switch this throw true try typeof uint ulong unchecked unsafe ushort using virtual volatile void while async await ascending descending from get group into join let orderby partial select set value var where yield";return{k:a,c:[{cN:"comment",b:"///",e:"$",rB:true,c:[{cN:"xmlDocTag",b:"///|"},{cN:"xmlDocTag",b:"?",e:">"}]},b.CLCM,b.CBLCLM,{cN:"preprocessor",b:"#",e:"$",k:"if else elif endif define undef warning error line region endregion pragma checksum"},{cN:"string",b:'@"',e:'"',c:[{b:'""'}]},b.ASM,b.QSM,b.CNM,{bK:"protected public private internal",e:/[{;=]/,k:a,c:[{bK:"class namespace interface",starts:{c:[b.TM]}},{b:b.IR+"\\s*\\(",rB:true,c:[b.TM]}]}]}});hljs.registerLanguage("javascript",function(a){return{aliases:["js"],k:{keyword:"in if for while finally var new function do return void else break catch instanceof with throw case default try this switch continue typeof delete let yield const class",literal:"true false null undefined NaN Infinity",built_in:"eval isFinite isNaN parseFloat parseInt decodeURI decodeURIComponent encodeURI encodeURIComponent escape unescape Object Function Boolean Error EvalError InternalError RangeError ReferenceError StopIteration SyntaxError TypeError URIError Number Math Date String RegExp Array Float32Array Float64Array Int16Array Int32Array Int8Array Uint16Array Uint32Array Uint8Array Uint8ClampedArray ArrayBuffer DataView JSON Intl arguments require"},c:[{cN:"pi",b:/^\s*('|")use strict('|")/,r:10},a.ASM,a.QSM,a.CLCM,a.CBLCLM,a.CNM,{b:"("+a.RSR+"|\\b(case|return|throw)\\b)\\s*",k:"return throw case",c:[a.CLCM,a.CBLCLM,a.REGEXP_MODE,{b:/,e:/>;/,r:0,sL:"xml"}],r:0},{cN:"function",bK:"function",e:/\{/,c:[a.inherit(a.TM,{b:/[A-Za-z$_][0-9A-Za-z$_]*/}),{cN:"params",b:/\(/,e:/\)/,c:[a.CLCM,a.CBLCLM],i:/["'\(]/}],i:/\[|%/},{b:/\$[(.]/},{b:"\\."+a.IR,r:0}]}});hljs.registerLanguage("css",function(a){var b="[a-zA-Z-][a-zA-Z0-9_-]*";var c={cN:"function",b:b+"\\(",e:"\\)",c:["self",a.NM,a.ASM,a.QSM]};return{cI:true,i:"[=/|']",c:[a.CBLCLM,{cN:"id",b:"\\#[A-Za-z0-9_-]+"},{cN:"class",b:"\\.[A-Za-z0-9_-]+",r:0},{cN:"attr_selector",b:"\\[",e:"\\]",i:"$"},{cN:"pseudo",b:":(:)?[a-zA-Z0-9\\_\\-\\+\\(\\)\\\"\\']+"},{cN:"at_rule",b:"@(font-face|page)",l:"[a-z-]+",k:"font-face page"},{cN:"at_rule",b:"@",e:"[{;]",c:[{cN:"keyword",b:/\S+/},{b:/\s/,eW:true,eE:true,r:0,c:[c,a.ASM,a.QSM,a.NM]}]},{cN:"tag",b:b,r:0},{cN:"rules",b:"{",e:"}",i:"[^\\s]",r:0,c:[a.CBLCLM,{cN:"rule",b:"[^\\s]",rB:true,e:";",eW:true,c:[{cN:"attribute",b:"[A-Z\\_\\.\\-]+",e:":",eE:true,i:"[^\\s]",starts:{cN:"value",eW:true,eE:true,c:[c,a.NM,a.QSM,a.ASM,a.CBLCLM,{cN:"hexcolor",b:"#[0-9A-Fa-f]+"},{cN:"important",b:"!important"}]}}]}]}]}});hljs.registerLanguage("xml",function(a){var c="[A-Za-z0-9\\._:-]+";var d={b:/<\?(php)?(?!\w)/,e:/\?>/,sL:"php",subLanguageMode:"continuous"};var b={eW:true,i:/,r:0,c:[d,{cN:"attribute",b:c,r:0},{b:"=",r:0,c:[{cN:"value",v:[{b:/"/,e:/"/},{b:/'/,e:/'/},{b:/[^\s\/>]+/}]}]}]};return{aliases:["html"],cI:true,c:[{cN:"doctype",b:"",r:10,c:[{b:"\\[",e:"\\]"}]},{cN:"comment",b:"",r:10},{cN:"cdata",b:"<\\!\\[CDATA\\[",e:"\\]\\]>",r:10},{cN:"tag",b:"",rE:true,sL:"css"}},{cN:"tag",b:"
4 |
5 |
6 |
7 |
8 | [rtoc]: #roottoc "Table of Contents" class=backref
9 |
10 | # MarkdownTools Developer Guide [roottoc]
11 |
12 | ------
13 |
14 | * [mdmerge Specifications][spectoc]
15 | * [Setting up Python Virtual Environments][venvtoc]
16 | * [Git procedures for the project][gittoc]
17 |
18 | ------
19 |
20 | <<[specifications.mmd]
21 |
22 | <<[venv.mmd]
23 |
24 | <<[git-procedures.mmd]
25 |
--------------------------------------------------------------------------------
/docs/git-procedures.mmd:
--------------------------------------------------------------------------------
1 | Title: Git procedures for the project
2 |
3 | [gtoc]: #gittoc "Section Contents" class=backref
4 |
5 | # Git procedures for the project [⇑][rtoc] [gittoc]
6 |
7 | * [Branch naming][gitbra]
8 | * [Tag naming][gittag]
9 | * [Creating the local respository][gitlcl]
10 | * [Setting your prompt to show the current branch][gitcur]
11 | * [Topic branch workflow][gittop]
12 | - [Create the topic branch][]
13 | - [Commit early and often][]
14 | - [Rebase the topic branch before merging][]
15 | - [Merge the topic branch][]
16 | - [Delete the topic branch][]
17 | - [Push the commit][]
18 | * [Merging changes between python2 and python3 branches][gitmrg]
19 | * [Making a release][gitrel]
20 |
21 | These are the procedures I use for managing the local and remote git repos for this project. I use the command line for all my git work on this project.
22 |
23 | If you primarily use a GUI tool, then much of this might not be helpful. However, if you want to contribute, or you just want to understand what I could possibly have been thinking when I set all this up, then you should still read these sections:
24 |
25 | * [Branch naming][]
26 | * [Tag naming][]
27 |
28 | ## Branch naming [⇑][gtoc] [gitbra]
29 |
30 | The main production code lives in these branches. There are stable branches:
31 |
32 | * `master`
33 | * `python2/stable`
34 | * `python3/stable`
35 |
36 | Those contain the 1.0, 1.1, etc. versions.
37 |
38 | There are the current development branches:
39 |
40 | * `master.dev`
41 | * `python2/dev`
42 | * `python3/dev`
43 |
44 | They contain the 1.0rc1, 1.0rc2, 1.1a, 1.1b, etc. versions.
45 |
46 | Topic branches are used to work on a specific feature or defect. They are the same as a stable or dev branch, appended with a short topic name that always starts with "`.t-`". For example, the branch `python3/dev.t-addFailTests` would be the name of a topic branch that would be used to create some additional tests for some illconditioned inputs or other specific failure cases; the branch `python3/stable.t-issue123` would be the name of a topic branch for a fix to address a particular issue in a released version of the code.
47 |
48 | ## Tag naming [⇑][gtoc] [gittag]
49 |
50 | Tags are assigned when a stable or dev version is released. The tag name has the form "v{version}/{branch-root}", like this:
51 |
52 | * `v1.0rc3/master`
53 | * `v1.0rc3/python2`
54 | * `v1.0rc3/python3`
55 |
56 | The message on the tag is similar to the name. The message has the form "{version} {branch-root}". So a command to add a tag might look like:
57 |
58 | ```bash
59 | $ git tag -a v1.0rc4/master -m "v1.0rc4 master"
60 | ```
61 |
62 | ## Creating the local respository [⇑][gtoc] [gitlcl]
63 |
64 | This command creates the local repository and adds a local branch "`master`" that tracks the remote `origin\master` branch.
65 |
66 | ```bash
67 | $ git clone https://github.com/JeNeSuisPasDave/MarkdownTools.git
68 | ```
69 |
70 | You'll need to create local branches for any other branch you work in, and make sure they track the corresponding remote branch. For example:
71 |
72 | ```bash
73 | $ git branch --track python2/dev origin/python2/dev
74 | $ git branch --track python3/dev origin/python3/dev
75 | ```
76 |
77 | The `git branch -vv` command will show you the remote branch, if any, assocated with each local branch.
78 |
79 | ## Setting your prompt to show the current branch [⇑][gtoc] [gitcur]
80 |
81 | It is helpful to know what branch you are in and whether the branch is dirty. If you are using a bash shell, then you can add this bit of code to your `.bash_profile`. It will show the current branch (if any) and a dirty flag (`*`) in cyan, the current directory in green, and then move the cursor to the start of the next line.
82 |
83 | ```bash
84 | # produce a '*' if the git status is 'dirty'
85 | #
86 | function parse_git_dirty {
87 | [[ $(git status 2> /dev/null | tail -n1) \
88 | != "nothing to commit, working directory clean" ]] \
89 | && echo "*"
90 | }
91 |
92 | # produce the current git branch name
93 | #
94 | function parse_git_branch {
95 | git branch --no-color 2> /dev/null \
96 | | sed -e '/^[^*]/d' -e "s/* \(.*\)/[\1$(parse_git_dirty)]/"
97 | }
98 |
99 | # Black 0;30 Dark Gray 1;30
100 | # Blue 0;34 Light Blue 1;34
101 | # Green 0;32 Light Green 1;32
102 | # Cyan 0;36 Light Cyan 1;36
103 | # Red 0;31 Light Red 1;31
104 | # Purple 0;35 Light Purple 1;35
105 | # Brown 0;33 Yellow 1;33
106 | # Light Gray 0;37 White 1;37
107 | #
108 | PS1="\w\$ "
109 | PS1="\[\033[1;36m\]\$(parse_git_branch)\[\033[1;32m\]\w\$\[\033[0m\]\n"
110 | export PS1
111 |
112 | ```
113 |
114 |
115 | ## Topic branch workflow [⇑][gtoc] [gittop]
116 |
117 | Let's suppose you want to fix a reported issue. You start looking at the code in the python3/stable branch.
118 |
119 | ### Create the topic branch
120 |
121 | The first thing you *should* do is to create a topic branch. Like this:
122 |
123 | ```bash
124 | $ git checkout -b python3/stable.t-issue45
125 | ```
126 |
127 | But often you just start working until you realize are working in a main branch and it is dirty and you neglected to create the topic branch. That's OK because you can *still* use that same command to create the topic branch (as long as you haven't done a `git add` or `git commit` you are free to create the topic branch without any trouble).
128 |
129 | ### Commit early and often
130 |
131 | A topic branch gives you lots of freedom and lots of privacy. Unless you push it to the remote, no one else is going to see what you are doing. Therefore there are no constraints to how often you can make commits or how stable you think the code is that you are committing. Feel free to commit as often as you'd like. And when you commit, make a nice commit comment that explains what you are doing and why you are doing it. Don't worry about how the commit message reads; just give it as much information as you can so that when you read it again later next week you'll have some idea what you were talking about.
132 |
133 | Besides the intrinsic value of commits as checkpoints and signposts in the history of the code, why is it OK to make lots of little commits and to commit breaking changes or partial work? Because you are going to clean all that up before you merge your change back into the main production or dev branches.
134 |
135 | ### Rebase the topic branch before merging
136 |
137 | The goal is to do a single commit from the topic branch back to the main branch, and to make that commit a fast-forward commit, not a merge. Doing so requires two preparation steps:
138 |
139 | 1. Rebase from the main branch
140 | 2. Squash topic branch commits
141 |
142 | The main branch might have changed since the point at which you created the topic branch. If those changes are in the same files you've been changing in the topic branch, then a merge needs to happen. And the best place for the merge to happen is in the topic branch. That is because we don't want to see those merge commits in the main branch, and because doing the merge in the topic branch gives you time to test the merged code and be sure everything is still working, or correct any problems the merge introduced.
143 |
144 | #### Rebase from the main branch
145 |
146 | To bring the main branch changes into the topic branch, you want to rebase. Assuming that we have a topic branch called `python3/dev.t-something`, the commands looks like:
147 |
148 | ```bash
149 | $ git checkout python3/dev
150 | $ git fetch origin
151 | $ git merge --ff-only origin/python3/dev
152 | $ git checkout python3/dev.t-something
153 | $ git rebase python3/dev
154 | ```
155 |
156 | If `git rebase` stops prematurely due to a merge conflict, you can resolve the conflict (make sure to update the index with `git add --all .`) and then use the command `git rebase --continue` to proceed with the remaining steps of the rebase. If the merge conflict needs to be addressed later or in some other way, then you can use the command `git rebase --abort` to roll back the rebase.
157 |
158 | #### Squash topic branch commits
159 |
160 | Your topic branch will contain, typically, a lot of commits. But you don't want to pollute the main branch with all those little changes. To address this you squash the commits together into a single commit with a single lucid and complete message. The commands to do that look like:
161 |
162 | ```bash
163 | $ git checkout python3/dev.t-something
164 | $ git rebase --interactive python3/dev
165 | ```
166 |
167 | What that does it throw you into `vim`, or whatever your default editor is, with a list of commits, each beginning with the word "pick". You need to change each and every one of those "pick"s to a "squash" or an "s", then save the "file". You'll next be presented with a combined checking message, a concatenation of all the commit messages from all the commits in the topic branch back to the beginning of the main branch. Edit that text until it describes the change you are about to merge into the main branch.
168 |
169 | ### Merge the topic branch
170 |
171 | Then you use the following commands (branch names changes as appropriate) to merge the topic branch change into the main branch:
172 |
173 | ```bash
174 | $ git checkout python3/dev
175 | $ git merge --ff-only python3/dev.t-something
176 | ```
177 |
178 | If a fast forward merge cannot be done, then you'll need to update the main branch and rebase the topic branch (as per step 1); then repeat step 2. Again, we want to do merging and conflict resolution on a topic branch, not the main branch.
179 |
180 | ### Push the commit
181 |
182 | Push the commit to the remote repository. With the main branch still checked out, use the following command.
183 |
184 | ```bash
185 | $ git push origin
186 | ```
187 |
188 | ### Delete the topic branch
189 |
190 | Once the changes are squashed and merged back into the main branch, there is no reason to keep the topic branch around, so you should delete it.
191 |
192 | ```bash
193 | $ git branch -d python3/dev.t-something
194 | ```
195 |
196 | If you had pushed the topic branch to the remote repository (perhaps you were collaborating with other developers on it) then you can delete the remote branch with this command.
197 |
198 | ```bash
199 | $ git push origin :python3/dev.t-something
200 | ```
201 |
202 | ## Merging changes between python2 and python3 branches [⇑][gtoc] [gitmrg]
203 |
204 | Typically you will work primarily with one version of Python, with one branch of the code. Once everything is working with that verion of Python, you will port the changes to the branch associated with the other version of Python. I recommend starting with Python 3 for anything that is not specifically a Python 2 issue.
205 |
206 | When it comes time to port the changes from the Python 3 branch to the Python 2 branch, I use a different command for injecting a new file versus modifying an existing file.
207 |
208 | To insert a new file from the Python 3 branch into the Python 2 branch, you can do something like this:
209 |
210 | ```bash
211 | $ git show python3/dev.t-something:tests/data/interesting-new-issue.md tests/data/interesting-new-issue.md
212 | ```
213 |
214 | To merge changes to an existing file, you can use this command:
215 |
216 | ```bash
217 | $ git checkout -p python3/dev.t-something tests/test_MarkdownMerge.py
218 | ```
219 |
220 | That will produce a patch and then interactively prompt you to accept or reject each difference. `y` to accept, `n` to reject, and `a` to accept every remaining difference. Sometimes the difference displayed is actually several short differences; if you only want a subset of those smaller differences, then `s` will split the bundled differences and let you select just the ones you want. Other options are available.
221 |
222 | Of course, deleting a file is straightforward:
223 |
224 | ```bash
225 | $ git rm tests/data/no-longer-used.mmd
226 | ```
227 |
228 | ## Making a release [⇑][gtoc] [gitrel]
229 |
230 | When a release is ready to publish, the following steps are required:
231 |
232 | 1. Both the `python2/*` and `python3/*` branches unit tests pass.
233 | 2. The version number in `__init__.py` is changed to match the new release.
234 | 3. The `CHANGELOG.md` file in the `master` or `master.dev` branch has been updated to reflect the changes.
235 | 4. All the local commits to the three main branches have been pushed to the remote repository.
236 | 5. The `makedist.sh` and `uploaddist.sh` scripts have been run for both the `python2/*` and `python3/*` branches.
237 |
238 | With the successful completion of those steps, the release is nearly complete. The only remaining step is to tag the release commits. The best way to do that is to checkout each main branch (dev or stable) and tag each, then push to the remote repository. For example:
239 |
240 | ```bash
241 | $ git checkout python2/stable
242 | $ git tag -a v1.0.2/python2 -m "v1.0.2 python2"
243 | $ git checkout python3/stable
244 | $ git tag -a v1.0.2/python3 -m "v1.0.2 python3"
245 | $ git checkout main/stable
246 | $ git tag -a v1.0.2/main -m "v1.0.2 main"
247 | $ git push --tags origin
248 | ```
249 |
250 |
--------------------------------------------------------------------------------
/docs/make-docs.cmd:
--------------------------------------------------------------------------------
1 | @echo off
2 | @cd ..\design
3 | @call .\make-docs.cmd
4 | @copy *.html ..\docs /y
5 | @copy *.png ..\docs /y
6 | @cd ..\AdaptiveModelingWorkflowApi\docs
7 | @call .\make-docs.cmd
8 | @copy *.html ..\..\docs /y
9 | @cd ..\..\ModelUpdateApi\docs
10 | @call .\make-docs.cmd
11 | @copy *.html ..\..\docs /y
12 | @cd ..\..\docs
13 | @IF NOT EXIST .\css MKDIR css
14 | @ROBOCOPY /NS /NC /NFL /NDL /NP /NJH /NJS /S /MIR ..\docs-support\css .\css
15 | @IF NOT EXIST .\js MKDIR js
16 | @ROBOCOPY /NS /NC /NFL /NDL /NP /NJH /NJS /S /MIR ..\docs-support\js .\js
17 | @IF NOT EXIST .\styles MKDIR styles
18 | @ROBOCOPY /NS /NC /NFL /NDL /NP /NJH /NJS /S /MIR ..\docs-support\styles .\styles
19 |
--------------------------------------------------------------------------------
/docs/make-docs.sh:
--------------------------------------------------------------------------------
1 | #! /bin/bash
2 | #
3 |
4 | # build the styles
5 | #
6 | pushd ../docs-support > /dev/null
7 | ./make-docs.sh
8 | popd > /dev/null
9 |
10 | # update the styles and JavaScript in this docs folder
11 | #
12 | [ -d "css" ] || mkdir css
13 | [ -d "js" ] || mkdir js
14 | [ -d "styles" ] || mkdir styles
15 | curDir=`pwd`
16 | rootDir=${curDir%/*}
17 | rsync -a $rootDir/docs-support/css/ $curDir/css
18 | rsync -a $rootDir/docs-support/js/ $curDir/js
19 | rsync -a $rootDir/docs-support/styles/ $curDir/styles
20 |
21 | # generate the html
22 | #
23 | mdmerge devguide.mmd | multimarkdown > devguide.html
--------------------------------------------------------------------------------
/docs/specifications.mmd:
--------------------------------------------------------------------------------
1 | Title: mdmerge Specifications
2 |
3 | [stoc]: #spectoc "Section Contents" class=backref
4 |
5 | # mdmerge Specifications [⇑][rtoc] [spectoc]
6 |
7 | * [unresolved issues][specissues]
8 | * [filepaths][specpaths]
9 | * [Interpreting index files][specidxs]
10 | - [LeanPub index files][]
11 | - [mmd_merge index files][]
12 | * [Interpreting include declarations][specdecl]
13 | - [MultiMarkdown transclusion syntax][]
14 | - [Marked inclusion syntax][]
15 | - [LeanPub code inclusion syntax][]
16 | * [Command Line Syntax][speccli]
17 | - [options][]
18 |
19 | ## unresolved issues [⇑][stoc] [specissues]
20 |
21 | *Note: These are just issues I've thought about addressing; no active plans to fix these at the moment.*
22 |
23 | * error handling should be configurable ... output html error page, output system exit code, fail silently, et cetera.
24 | * handle missing files in CLI better
25 | * need unit tests for absolute file paths
26 | * need unit tests for home (`~`) file paths
27 | * perhaps it should strip trailing line breaks? (i.e. so that included files only have one terminating `'\n'`)
28 |
29 | ## filepaths [⇑][stoc] [specpaths]
30 |
31 | Unless otherwise specified, all file path are specified as:
32 |
33 | * Absolute (starts with `/`)
34 | * Home (starts with `~/`) in which the tilde means the users home directory
35 | * Relative (starts with something other than `/` or `~/`) to the file that includes them.
36 |
37 | ## Interpreting index files [⇑][stoc] [specidxs]
38 |
39 | ### LeanPub index files
40 |
41 | If the first line of the file is `frontmatter:` then the file is recognized as a LeanPub index file. If the filename is `book.txt` and the CLI option `--leanpub` was used, then the file is recognized as a Leanpub index file (whether or not it contains a `frontmatter:` line).
42 |
43 | The processing rules for **LeanPub index files** are:
44 |
45 | 1. The remaining lines are treated as filepaths of files to be merged together.
46 | 1. Blank lines are ignored
47 | 1. Lines beginning with a `#` are ignored
48 | 1. Lines consisting of `frontmatter:`, `mainmatter:`, and `backmatter:` are ignored.
49 | 1. Lines that specify invalid file syntax or specify files that don't exist will be ignored, except that a warning message will be written to stderr.
50 | 1. Leading whitespace is ignored
51 | 1. A blank line is inserted between merged files
52 |
53 | The filepaths in the index file can be absolute, relative to the index file, and can use the `~` syntax for the user's home directory.
54 |
55 | ### mmd_merge index files
56 |
57 | If the first line of the file is `#merge` then the file is recognized a mmd_merge index file.
58 |
59 | The processing rules for **mmd_merge index files** are:
60 |
61 | 1. The remaining lines are treated as filepaths of files to be merged together.
62 | 1. Blank lines are ignored
63 | 1. Lines beginning with a `#` are ignored
64 | 1. Lines consisting of `frontmatter:`, `mainmatter:`, and `backmatter:` are ignored.
65 | 1. Lines that specify invalid file syntax or specify files that don't exist will be ignored, except that a warning message will be written to stderr.
66 | 1. Leading whitespace is significant in that each tab or every 4 spaces is treated as an increase in header level (so a single tab indent would change convert an h1 to an h2; a double tab indent would convert an h1 to an h3).
67 | 1. A blank line is inserted between merged files
68 |
69 | From the insource documentation of the mmd_merge utility:
70 |
71 | > This script is designed to allow you to use different files to store parts of a larger MultiMarkdown document, making it easier to reorganize the document if you so desire. Each line consists of the url or filename of the next document. If the line is indented, each tab (or 4 spaces) will increase the header level of the document by 1 (similar to the `Base Header Level` metadata). Blank lines are ignored. Lines starting with `#` are treated as comments. Only metadata from the first file would be properly handles, since it would be the only metadata at the top of the new "virtual" document.
72 |
73 | The filepaths in the index file can be absolute, relative to the index file, and can use the `~` syntax for the user's home directory.
74 |
75 | ## Interpreting include declarations [⇑][stoc] [specdecl]
76 |
77 | ### MultiMarkdown transclusion syntax
78 |
79 | The transclusion syntax was introduced in MultiMarkdown 4.5. An include declaration is matched as a **MultiMarkdown file transclusion** if it has the following form:
80 |
81 | 1. A blank line, followed by
82 | 1. A line containing only `{{filepath}}`, followed by
83 | 1. Another blank line.
84 |
85 | The filepath can be absolute, relative to the root file, and can use the `~` syntax for the user's home directory.
86 |
87 | Files included in this manner will themselves be examined for further include declarations or as index files.
88 |
89 | Another format matching MultiMarkdown file transclusion is:
90 |
91 | 1. A blank line, followed by
92 | 1. A code fence start (e.g. `` ``` `` or `` ```python `` or similar, followed by
93 | 1. A line containing only `{{filepath}}`, followed by
94 | 1. A code fence termination (e.g. `` ``` ``), followed by
95 | 1. Another blank line.
96 |
97 | The filepath can be absolute, relative to the root file, and can use the `~` syntax for the user's home directory.
98 |
99 | Files matched in this manner will not be examined for further include declarations or index file specification. They will be included as is, including trailing line breaks.
100 |
101 | In any case the filename may be specified with a wildcard file extension (e.g., `name.*`). In this case MultiMarkdown will substitute an extension by the export format. This utility will substitute the wildcard in one of these ways:
102 |
103 | * If the command line flag `--export-target html` is specified, replace `.*` with `.html`
104 | * If the command line flag `--export-target latex` is specified, replace `.*` with `.tex`
105 | * If the command line flag `--export-target lyx` is specified, replace `.*` with `.lyx`
106 | * If the command line flag `--export-target opml` is specified, replace `.*` with `.opml`
107 | * If the command line flag `--export-target rtf` is specified, replace `.*` with `.rtf`
108 | * If the command line flag `--export-target odf` is specified, replace `.*` with `.odf`
109 | * If the command line flag `--export-target` is unspecified, replace `.*` with the same extension as the current file (the file containing the include declaration)
110 |
111 | ### Marked inclusion syntax
112 |
113 | A declaration is matched as a **Marked inclusion** if it has the form:
114 |
115 | 1. A blank line, followed by
116 | 2. A line containing only `<<[filepath]`, followed by
117 | 3. Another blank line.
118 |
119 | The filepath can be absolute, relative to the root file, and can use the `~` syntax for the user's home directory.
120 |
121 | ### Marked raw file inclusion syntax
122 |
123 | A declaration is matched as a **Marked raw file inclusion** if it has the form:
124 |
125 | 1. A blank line, followed by
126 | 2. A line containing only `<<{filepath}`, followed by
127 | 3. Another blank line.
128 |
129 | The filepath can be absolute, relative to the root file, and can use the `~` syntax for the user's home directory.
130 |
131 | Raw file processing is affected by the `--just-raw` CLI option. If not specified, then all raw file specifications lines are converted to HTML comment lines ... like ``. However, if the `--just-raw` CLI option is specified, then **only** raw file specifications are process (including those inside HTML comments) and other kinds of include specifications are ignore.
132 |
133 | The specified file is just inserted as is into the output text. Raw files are not processed for additional include statements.
134 |
135 | ### LeanPub code inclusion syntax
136 |
137 | A declaration is matched as **LeanPub code inclusion** if it has the form:
138 |
139 | 1. A blank line, followed by
140 | 2. A line containing only `<<(filepath)`, followed by
141 | 3. Another blank line.
142 |
143 | The filepath can be absolute, relative to the root file, and can use the `~` syntax for the user's home directory.
144 |
145 | An declaration is also matched as LeanPub code inclusion if it has the form:
146 |
147 | 1. A blank line, followed by
148 | 2. A line containing only `<<[code title](filepath)`, followed by
149 | 3. Another blank line.
150 |
151 | The filepath can be absolute, relative to the root file, and can use the `~` syntax for the user's home directory.
152 |
153 | In this form, however, the text in `[code title]` is *not* used as a caption (although that is what LeanPub would do); it is ignored.
154 |
155 | Note: Unlike Marked inclusion, wildcard file extension substitution is not performed with LeanPub code inclusion.
156 |
157 | ## Command Line Syntax [⇑][stoc] [speccli]
158 |
159 | The command line looks like this:
160 |
161 | ```no-highlight
162 | mdmerge [options] [-o outputfile] inputfiles
163 | mdmerge [options] [-o outputfile] -
164 | ```
165 |
166 | ### options
167 |
168 | `options`
169 | : One or more of `--book`, `--export-target`, `--ignore-transclusions`, `--just-raw`, `--leanpub`, `--version`, `--help`, `-h`, `-?`.
170 |
171 | `--book`
172 | : Treat STDIN as an index file (a "book" file).
173 |
174 | `--export-target [html|latex|lyx|opml|rtf|odf]`
175 | : Indicates the ultimate output target of the markdown processor, but primarily impacts wildcard substitution in Marked inclusion.
176 |
177 | `--ignore-transclusions`
178 | : Leave any MultiMarkdown transclusion specifications alone; do not include
179 | the specified file. Useful if you want to mix Marked/LeanPub includes and
180 | MultiMarkdown includes, but have MultiMarkdown handline the transclusions.
181 |
182 | `--just-raw`
183 | : Ignore all include specifications except for raw includes; useful for
184 | processing the output of the Markdown processor to pick up the raw file include
185 | specifications that should have passed through untouched.
186 |
187 | `--leanpub`
188 | : Indicates that any input file named `book.txt` should be treated as a LeanPub index file.
189 |
190 | `--version`
191 | : Gives the version information about the utility.
192 |
193 | `-o outputfile`
194 | : The filepath in which to store the merged text. If not specified, then STDOUT is used.
195 |
196 | `--outfile outputfile`
197 | : same as `-o`.
198 |
199 | `inputfiles`
200 | : A list of space separated input files that can be merged together. If multiple files are given, they are treated as if they were specified in a LeanPub index file.
201 |
202 | `-`
203 | : The input comes from STDIN.
204 |
205 | `--help`
206 | : Help information
207 |
208 | `-h`
209 | : Help information
210 |
211 | `-?`
212 | : Help information
213 |
--------------------------------------------------------------------------------
/docs/venv.mmd:
--------------------------------------------------------------------------------
1 | Title: Setting up Python Virtual Environments
2 |
3 | [vtoc]: #venvtoc "Section Contents" class=backref
4 |
5 | # Setting up Python Virtual Environments [⇑][rtoc] [venvtoc]
6 |
7 | * [Installing the virtualenv package][venvinstall]
8 | * [Creating virtual environments][venvcreate]
9 | * [Activating the virtual environment][venvact]
10 | * [Deactivating the virtual environment][venvdeact]
11 |
12 | This project delivers both a Python 2 and Python 3 release. It needs to be tested in multiple versions of Python. The best way to do that is to setup virtal Python environments that you can easily switch between. I like using `virtualenv` to do that.
13 |
14 | I am assuming here that you have both Mac Ports python27 and python33 installed on your OS X system. If you use brew or fink or something similar, you can make the necessary adjustments in the location of the respective Python framework paths.
15 |
16 | ## Installing the virtualenv package [⇑][vtoc] [venvinstall]
17 |
18 | To install virtualenv, use either:
19 |
20 | ```bash
21 | $ sudo /opt/local/Library/Frameworks/Python.framework/Versions/2.7/bin/pip install virtualenv
22 | $ sudo /opt/local/Library/Frameworks/Python.framework/Versions/3.3/bin/pip install virtualenv
23 | ```
24 |
25 | or
26 |
27 | ```bash
28 | $ sudo /opt/local/Library/Frameworks/Python.framework/Versions/2.7/bin/easy_install install virtualenv
29 | $ sudo /opt/local/Library/Frameworks/Python.framework/Versions/3.3/bin/easy_install install virtualenv
30 | ```
31 |
32 | ## Creating virtual environments [⇑][vtoc] [venvcreate]
33 |
34 | ### Setting up a Python 2.7 virtual environment
35 |
36 | ```bash
37 | $ cd myproject
38 | $ /opt/local/Library/Frameworks/Python.framework/Versions/2.7/bin/virtualenv venv27
39 | ```
40 |
41 | ### Setting up a Python 3.3 virtual environment
42 |
43 | ```bash
44 | $ cd myproject
45 | $ /opt/local/Library/Frameworks/Python.framework/Versions/3.3/bin/virtualenv venv33
46 | ```
47 |
48 | ## Activating the virtual environment [⇑][vtoc] [venvact]
49 |
50 | ### Activating the Python 2.7 virtual environment
51 |
52 | ```bash
53 | $ cd myproject
54 | $ . venv27/bin/activate
55 | (venv27)$ python --version
56 | Python 2.7.6
57 | (venv27)$
58 | ```
59 |
60 | ### Activating the Python 3.3 virtual environment
61 |
62 | ```bash
63 | $ cd myproject
64 | $ . venv33/bin/activate
65 | (venv33)$ python --version
66 | Python 3.3.4
67 | (venv33)$
68 | ```
69 |
70 | ## Deactivating the virtual environment [⇑][vtoc] [venvdeact]
71 |
72 | ### Deactivating the Python 2.7 virtual environment
73 |
74 | ```bash
75 | (venv27)$ deactivate
76 | $ python --version
77 | Python 2.7.5
78 | $
79 | ```
80 |
81 | ### Deactivating the Python 3.3 virtual environment
82 |
83 | ```bash
84 | (venv33)$ deactivate
85 | $ python --version
86 | Python 2.7.5
87 | $
88 | ```
89 |
--------------------------------------------------------------------------------