This readme is intended to walk new users throught the steps to clone the git repository containing the example specification converted to Markdown, edit the specification, and prodcue HTML and PDF versions of the specification from the Markdown source.
This readme is intended to walk new users throught the steps to clone the git repository containing the example specification converted to Markdown, edit the specification, and prodcue HTML and PDF versions of the specification from the Markdown source. By the end of this guide, you should have successfully converted [38331-i00.md](https://forge.etsi.org/rep/fevold/markdown-specification/-/raw/main/38331-i00.md?ref_type=heads) to [38331-i00.pdf](https://forge.etsi.org/rep/fevold/markdown-specification/-/raw/main/examples/38331-i00.pdf?ref_type=heads&inline=false). There are some manual steps required, but these steps are automatable, and will be automated in the future.
## Markdown Basics
Markdown is the file format that is being proposed to write the next generation of 3GPP specifications. Markdown is a language used to present information and not much else. Therefore, the set of features is limited, and through the process we develop, we will add details in post-processing. This allows delegates to focus on the technical aspects while still enabling a professional-grade specification to be produced in the end for public consumption.
### Basic Elements
Markdown supports a variety of basic organizational elements.
The following basic elements are supported.
* Headings
* Paragraphs
* Line Breaks
* Text Bolding
* Text Italicization
* Text Bolding and Italicization
* Block quotes
* Ordered Lists
* Unordered Lists
* Code Blocks
* Images
* Horizontal Rules
* Links
* References
* Inline HTML
More details can be found at [Markdown Guide](https://www.markdownguide.org/basic-syntax/).
### Special Characters
Special characters, used in Markdown syntax, must be preceded by a \\ character to display properly when part of the text. The only exception is for raw blocks of text and code blocks, which start and end with \`\`\` and \~\~\~, respectively.
Details on special characters can be found at [Markdown Guide](https://www.markdownguide.org/basic-syntax/#escaping-characters).
# Converting Markdown to HTML and PDF
The main steps that will be taken during this exercise after the prerequisite steps are run:
1. Run `md_to_html.bat` to convert the Markdown file to HTML and apply post-processing
- Procedural text indentation
- ASN.1 indentation and colorization
- MSC signalling and block diagram rendering
2. In a manual step, you will copy the cover page and table of contents to the HTML file. This step will be automated in the future.
3. Run `html_to_pdf.bat` to convert the HTML file to PDF.
## Prerequisites
For the purpose of this demo repository, please download the exact versions of the prerequisite tools to limit the scope of bug fixes.
This demonstration assumes the use of Microsoft Windows 10 or 11. As needed, other platforms may be considered.
1. Git
- Instructions will be provided in this first version of the demo using the Git console.
- Download and install Git [here](https://git-scm.com/downloads/win).
...
...
@@ -104,7 +82,8 @@ After following these steps, you should be left with at least the following dire
- README.md
- weasyprint.exe
## Markdown to HTML
## Converting Markdown to HTML
The steps in this version of the instructions will require the use of the Windows Command Prompt, which can be accessed by clicking "Command Prompt" in the start menu in the "Windows System" folder. The process will eventually be executed by double clicking a script file, such as a "batch" or "BAT" file, which will automatically run through the steps according to a configuration.
1. Open a Windows Command Prompt
...
...
@@ -134,11 +113,13 @@ The steps in this version of the instructions will require the use of the Window
- Delete the text between the first line and the line preceding "\<h1 id="foreword"\>Foreword\</h1\>".
- Note that in Notepad++, this can be accomplished by clicking before the first line and holding ctrl+shift+B, clicking at the end of the line preceding the one described in the bullet above and holding ctrl+shift+B. Now the text is selected, and you can press the "del" key to delete the text, and then copy in the content of cover_toc_38331-i00.html.
## HTML to PDF
## Converting HTML to PDF
The last step is to convert the HTML to a PDF. To do so, execute the following command while in the scripts directory as in the previous steps.
> html_to_pdf.bat
# Rendering Steps
# Explanation of the Procedure
The following information is not required to run the tools and explains how the Markdown file is post-processed to produce the publishable, human-friendly versions of the specification.
The rendering steps are executed directly in Pandoc with scripts written in the [Lua](https://www.lua.org/docs.html) language. The benefit of using this method others which Pandoc supports is that Pandoc has a built-in Lua interpreter, meaning that the scripts are already in the context of the document in Pandoc's intermediate format, reducing the number of lines of code required substantially compared to other methods.
...
...
@@ -150,6 +131,7 @@ The main action in the Lua scripts is at the bottom of each file, with supportin
More details on the integration between Pandoc and Lua can be found [here](https://pandoc.org/lua-filters.html).
## ASN Rendering
To colorize and indent the ASN.1 source in the specification, post-processing is required. The post-processing script can be found in scripts/asn1_render.lua.
In the Markdown source, ASN1 blocks are wrapped in `~~~ asn1` and `~~~`, which are identified by the last function in the script.
Markdown is the file format that is being proposed to write the next generation of 3GPP specifications. Markdown is a language used to present information and not much else. Therefore, the set of features is limited, and through the process we develop, we will add details in post-processing. This allows delegates to focus on the technical aspects while still enabling a professional-grade specification to be produced in the end for public consumption.
## Basic Elements
Markdown supports a variety of basic organizational elements.
The following basic elements are supported.
* Headings
* Paragraphs
* Line Breaks
* Text Bolding
* Text Italicization
* Text Bolding and Italicization
* Block quotes
* Ordered Lists
* Unordered Lists
* Code Blocks
* Images
* Horizontal Rules
* Links
* References
* Inline HTML
More details can be found at [Markdown Guide](https://www.markdownguide.org/basic-syntax/).
## Special Characters
Special characters, used in Markdown syntax, must be preceded by a \\ character to display properly when part of the text. The only exception is for raw blocks of text and code blocks, which start and end with \`\`\` and \~\~\~, respectively.
Details on special characters can be found at [Markdown Guide](https://www.markdownguide.org/basic-syntax/#escaping-characters).
