Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 267 lines (189 sloc) 9.954 kB
d041cab @rickard-green OTP-8512 Add Erlangish MarkDown to Erlangish XML support
rickard-green authored
1 Erlangish Markdown Text Files
2 =============================
3
4 Introduction
5 ------------
6
7 If you are looking for information on how to build and install Erlang/OTP you
8 want to read the [$ERL_TOP/INSTALL.md][] document instead of this document
9 (where `$ERL_TOP` is the top source directory in the source tree).
10
11 All files with the `.md` suffix (as well as this file) are ordinary text files
12 written using a Markdown like notation, and can be read using an ordinary text
13 editor such as for example `emacs`.
14
15 This document describes how `*.md` files in the Erlang/OTP source tree should
16 be written.
17
18 > *NOTE*: Before modifying a `*.md` file read all of this document.
19
20 Erlangish Markdown
21 ------------------
22
23 We do not use Markdown straight out of the box. The Markdown syntax we use is
24 similar to the original Markdown but with a number of tweaks. The original
25 Markdown is documented at <http://daringfireball.net/projects/markdown/>. You
26 should read that documentation as well as this document before modifying any
27 Erlangish Markdown files in the Erlang/OTP source tree.
28
29 The original Markdown syntax was designed for generating HTML code from an
30 "easy to read/easy to write" plain text. Instead of generating HTML we generate
31 XML that fits into our documentation, i.e. we generate Erlangish XML from
32 Erlangish Markdown.
33
34 The `.md` suffix has been chosen since [github][] will generate HTML pages for
35 files with the `.md` suffix. Github does however not generate HTML according to
36 Erlangish Markdown, so some features do not work. The Erlangish Markdown
37 documents viewed at [our github repository][] will typically suffer from broken
38 links. The original Markdown script, gitub's Markdown, and our Erlangish
39 Markdown script will generate somewhat different results if you do not follow
40 indentation rules outlined in the Markdown documentation. You are encouraged to
41 try to write using a Markdown syntax that also looks nice on github. However,
42 it is *much* more important that the document is formatted correct in the
43 Erlang/OTP documentation.
44
45 ### Differences Between Markdown and Erlangish Markdown ###
46
47 #### Missing Features ####
48
49 This functionality is missing compared to Markdown version 1.0.1. Do not
50 depend on the fact that these features are missing. Some of them might appear
51 in the future.
52
53 * No inline HTML. Currently no inline XML is allowed either. Inline XML might
54 be allowed in the future, but there is no real need for it since we use
55 Erlangish Markdown for "readme"s that have a main purpose of being readable
56 in plain text.
57
58 * Backslash escapes all characters.
59
60 * No support for "horizontal rules".
61
62 * Links.
63 * No support for the "title" attribute.
64 * Automatic links does not support email addresses.
65
66 * Images.
67 * No support for the "title" attribute. Specified "title" will however
68 be used as `<icaption>`.
69 * No support for the "alt" attribute.
70
71 * Lists aren't supported inside block quotes.
72
73 * Link and image definition names *are* case sensitive.
74
75 #### Additional Features ####
76
77 * Automatic anchors at each heading.
78
79 * Optionally automatically generated table of contents.
80
81 * Note blocks.
82
83 * Warning blocks.
84
85 #### Extra requirements ####
86
87 * One and only one level 1 heading is allowed and required.
88
89 * The level 1 heading must be the first heading in the document.
90
91 * A level `X` heading must have a level `X-1` heading as parent heading.
92
93 * Link and image definition names aren't allowed to begin with a
94 question mark (?) character. Names beginning with a question mark have
95 been reserved for other use.
96
97 * The encoding of the file containing Erlangish Markdown should be
98 UTF-8.
99
100 ### Generated XML ###
101
102 > *WARNING*: The `emd2exml` script will blindly generate XML code according
103 > to the Erlangish Markdown in a file. Successfully generated XML does **not**
104 > imply that the generated XML adheres to used DTDs. `emd2exml` does very
105 > seldom fail and can easily generate XML that will cause the documentation
106 > build to fail. You always have to keep in mind that the XML generated
107 > should fit the chapter DTD of Erlang/OTP. Also note that even though HTML
108 > generation succeeds the PDF generation might fail, etc.
109 >
110 > *Always build the Erlang/OTP documentation after modifying an Erlangish
111 > Markdown document!*
112
113 A note about how we talk about "tags" below. When we say "generate(s) `<X>`
114 tags" this also imply that ending `</X>` tags will be generated at appropriate
115 places. Appropriate attributes to the `X` tag will also be generated.
116
117 * Inline and reference style links will either generate `<seealso>` tags
118 or `<url>` tags. If a "://" character sequence is found in the URL an
119 `<url>` tag will be generated; otherwise, a `<seealso>` tag is generated.
120
121 * Automatic links will only generate `<url>` tags. This since a
122 "://" character sequence have to be present in the URL in order
123 for the link to be identified.
124
125 * Inline and reference style images will generate a `<image file="...">
126 <icaption>...</icaption> </image>` sequence where the "title" will be
127 placed between `<icaption>` and `</icaption>`.
128
129 * Block quotes generate `<blockquote>` tags.
130
131 * If the first line of a top level block quote begins with a `> *NOTE*:`
132 character sequence, a `<note>` tag will be generated instead of a
133 `<blockquote>` tag. The note will span the entire block quote.
134
135 * If the first line of a top level block quote begins with a `> *WARNING*:`
136 character sequence, a `<warning>` tag will be generated instead of a
137 `<blockquote>` tag. The warning will span the entire block quote.
138
139 * Paragraphs will generate `<p>` tags.
140
141 * Break line (double trailing white space) will generate `<br/>` tags.
142
143 * An unordered list generates a `<list type="bulleted">` tag and `<item>`
144 tags for each item.
145
146 * An ordered list generates a `<list type="ordered">` tag and `<item>` tags
147 for each item.
148
149 * Code blocks will generate `<code type="none">` tags.
150
151 * Code span (backticks) will generate `<c>` tags.
152
153 * Emphasis (single `*` or `_`) will generate `<em>` tags.
154
155 * Strong emphasis (double `*` or `_`) will generate `<b>` tags.
156
157 * The level 1 heading will cause the following to be generated:
158
159 <?xml version="1.0" encoding="utf8" ?>
160 <!DOCTYPE chapter SYSTEM "chapter.dtd">
161 <chapter>
162 <header>
163 <copyright>
164 ...
165 </copyright>
166 <legalnotice>
167 ...
168 </legalnotice>
169
170 <title>...</title>
171 ...
172 <file>...</file>
173 </header>
174
175 ...
176
177 </chapter>
178
179 The content of copyright section and the legalnotice section will
180 contain information from a \%CopyrightBegin\%, \%CopyrightEnd\% block
181 if such exist (see below).
182
183 * A level `X` heading where `1 < X <= 3` will cause the the following
184 to be generated:
185
186 <marker id="..."/>
187 <section>
188 <title>...</title>
189 ...
190 </section>
191
192 The marker id is automatically generated as a combination of all parent
193 headings up to and including level 2 separated by a `_` character. As in
194 `<marker heading 2>_<marker heading 3>_ ... _<current marker heading>`
195 where each "marker heading" is constructed as follows. All characters a-z
196 and A-Z are kept as they are, space and tab characters are replaced by
197 `-` characters, and all other characters are dropped.
198
199 This way it is relatively easy to make sure that all marker ids of a
200 document are unique, but there is of course no guarantee that they are.
201
202 The upside of these auto generated markers is that we wont have to clutter
203 the document with XML or something else while being able to refer into
204 the document. The downside is that if you change a level 2 heading you
205 change a lot of marker ids which may break links into a document from
206 other documents. That is, *be careful* when changing headings in an
207 existing document.
208
209 * A level `X` heading where `3 < X` will cause the the following
210 to be generated:
211
212 <marker id="..."/>
213 <p><b>...</b></p>
214 ...
215
216 Current DTD:s used don't support deeper levels of sections, and we
217 therefore simulate a section this way. The marker id is generated as for
218 a true section (see above).
219
220 * If a section enclosed by \%CopyrightBegin\% and \%CopyrightEnd\% is
221 encountered, it will be interpreted as an EPL copyright and license,
222 and will be used in the header section of the document. The
223 \%CopyrightBegin\% and \%CopyrightEnd\% "tags" will be removed from
224 the output.
225
226 * All occurrences of \%OTP-REL% will be replaced by current release number
227 (e.g. R14A).
228
229 * All occurrences of \%ERTS-VSN% will be replaced by current ERTS version
230 (e.g. 5.8).
231
232 * Adding a `[?TOC]: true` line (optionally indented with three spaces)
233 anywhere in the document will cause a table of contents to be automatically
234 generated at the beginning of the generated document.
235
236 * Unicode characters (encoded in UTF-8) are allowed and will be passed
237 through as is to the output file.
238
239 Copyright and License
240 ---------------------
241
242 %CopyrightBegin%
243
244 Copyright Ericsson AB 2010. All Rights Reserved.
245
246 The contents of this file are subject to the Erlang Public License,
247 Version 1.1, (the "License"); you may not use this file except in
248 compliance with the License. You should have received a copy of the
249 Erlang Public License along with this software. If not, it can be
250 retrieved online at http://www.erlang.org/.
251
252 Software distributed under the License is distributed on an "AS IS"
253 basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
254 the License for the specific language governing rights and limitations
255 under the License.
256
257 %CopyrightEnd%
258
259
260
261 [$ERL_TOP/INSTALL.md]: doc/installation_guide:INSTALL
262 [github]: http://github.com
263 [our github repository]: http://github.com/erlang/otp
264
265
266 [?TOC]: true
Something went wrong with that request. Please try again.