Skip to content

Commit

Permalink
Improve markdown documentation.
Browse files Browse the repository at this point in the history 
Include desciptions of indenting, CDATA, and how image links are handled
relative to EML.
  • Loading branch information
@mbjones
mbjones committed Feb 12, 2018
1 parent 2f72c4f commit c70fcf0
Showing 1 changed file with 49 additions and 12 deletions.
61 changes: 49 additions & 12 deletions xsd/eml-text.xsd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -49,8 +49,7 @@
<section xmlns="">
<title>The eml-text module - Text field formatting</title>
<para>
The eml-text module is a wrapper container that allows general text descriptions to be used within the various modules of eml. It can include either structured or unstructured text blocks. It isn't really appropriate to use this module outside of the context of a parent module, because the parent module determines the appropriate context to which this text description applies. The eml-text module allows one to provide structure to a text description in order to convey concepts such as sections (paragraphs), hierarchy (ordered and unordered lists), emphasis (bold, superscript, subscript) etc. The structured elements can be specified using a subset of <ulink url="http://www.docbook.org">DocBook</ulink> so the predefined DocBook stylesheets can be used to style EML fields that implement this module, or alternatively can be specified using Markdown text blocks. Combinations of plain text, docbook sections, and markdown sections can be interleaved in any order, but most people will likely
find the markdown syntax the easiest to use.
The eml-text module is a wrapper container that allows general text descriptions to be used within the various modules of eml. It can include either structured or unstructured text blocks. It isn't really appropriate to use this module outside of the context of a parent module, because the parent module determines the appropriate context to which this text description applies. The eml-text module allows one to provide structure to a text description in order to convey concepts such as sections (paragraphs), hierarchy (ordered and unordered lists), emphasis (bold, superscript, subscript) etc. The structured elements can be specified using a subset of <ulink url="http://www.docbook.org">DocBook</ulink> so the predefined DocBook stylesheets can be used to style EML fields that implement this module, or alternatively can be specified using Markdown text blocks. Combinations of plain text, docbook sections, and markdown sections can be interleaved in any order, but most people will likely find the markdown syntax the easiest to use.
</para>
</section>
</doc:moduleDescription>
Expand All @@ -75,8 +74,7 @@
<xs:appinfo>
<doc:tooltip>Text</doc:tooltip>
<doc:summary>A simple text desription.</doc:summary>
<doc:description>The "text" element allows for both formatted and unformatted text blocks to be included in EML. It can contain a number of relevant subsections that allow the use of titles, sections, and paragraphs in the text block. This markup is
a subset of DocBook.
<doc:description>The "text" element allows for both formatted and unformatted text blocks to be included in EML. It can contain a number of relevant subsections that allow the use of titles, sections, and paragraphs in the text block. This markup is a subset of DocBook, or alternatively can be specified using Markdown text blocks.
</doc:description>
</xs:appinfo>
</xs:annotation>
Expand All @@ -96,8 +94,7 @@
<xs:appinfo>
<doc:tooltip>Paragraph</doc:tooltip>
<doc:summary>A simple paragraph of text.</doc:summary>
<doc:description>The "paragraph" element allows for both formatted and unformatted text blocks to be included in EML. It can be plain text or text with a limited set of markup tags, including emphasis, subscript, superscript, and lists. This markup
is a subset of DocBook.
<doc:description>The "paragraph" element allows for both formatted and unformatted text blocks to be included in EML. It can be plain text or text with a limited set of markup tags, including emphasis, subscript, superscript, and lists. This markup is a subset of DocBook.
</doc:description>
</xs:appinfo>
</xs:annotation>
Expand All @@ -107,12 +104,52 @@
<xs:appinfo>
<doc:tooltip>Markdown</doc:tooltip>
<doc:summary>A block of text formatted with Markdown directives.</doc:summary>
<doc:description>Markdown is a family of text-based formatting directives that can be used to
structure and format a block of text. A single markdown element in EML can contain multiple
formatting directives that support creation of sections and subsections with headings, a
wide variety of text formatting directives, the ability to include inline links to external
content, and the ability to embed inline citations, figures, and tables. EML's markdown element
follows the <ulink url="https://github.github.com/gfm/">GitHub Flavored Markdown (GFM)</ulink> extensions to the <ulink url="http://spec.commonmark.org/">CommonMark specification</ulink>.
<doc:description>
<para>
Markdown is a family of text-based formatting directives that can be used to
structure and format a block of text. A single markdown element in EML can contain multiple
formatting directives that support creation of sections and subsections with headings, a
wide variety of text formatting directives, the ability to include inline links to external
content, and the ability to embed inline citations, figures, and tables. EML's markdown element
follows the <ulink url="https://github.github.com/gfm/">GitHub Flavored Markdown (GFM)</ulink> extensions to the <ulink url="http://spec.commonmark.org/">CommonMark specification</ulink>. Clients that
display EML should use a markdown preprocessor to convert the Markdown formatting into an
appropriate display format such as HTML or PDF as appropriate. When a Markdown block is interleaved
with other blocks of text such as section and paragraph elements from Docbook, the Markdown section
should be interleaved as a block-level element in the flow of the document. This allows authors to
specify, for example, an initial section in DocBook, followed by a Markdown section, and then possibly
other sections in DocBook. This will likely be uncommon because Markdown and Docbook have similar
formatting capabilities, but it may be helpful when converting legacy documents that use DocBook.
</para>
<para>
Because markdown uses special characters that might be reserved by XML processors, one
must be careful to escape such characters, which is typically done by embedding the
text in a CDATA block, or other XML escaping measures. These escape sequences must be
unescaped before parsing the text with a Markdown processor.
</para>
<para>
Within a Markdown block, one can use embedded images to specify the location where an inline image
should be displayed within the document. For example, he syntax for an embedded image uses the
markdown reference syntax, for example <code>![Figure 1][fig.1.ab567w]</code>, where "fig.1.ab567w"
is the unique <code>id</code> attribute for the entity containing the reference to the image. When
client tools process such image links, they should inline the image data from that entity at the
location specified, which may involve , for example, resolving the image url from an
<code>otherEntity</code> section. This means that there is an implied link in all Markdown
documents of the form <code>[id]: url/to/image "Optional title attribute"</code>, which is derived
from the metadata for each entity within a document. Users do not need to insert these links in
order to use them, but client software that might be generating HTML from the markdown will likely
need to generate them from the entity metadata if they are using an external Markdown pre-processor
to handle conversion to HTML and other languages.
</para>
<para>
Because bulleted lists and other structures within Markdown are dependent on indenting the raw
markdown text, authors and processors should pay close attention to formatting within the
markdown block. In particular, if the XML document within which the markdown block is embedded
is in an indented hierarchy, then the first non-whitespace character of the markdown block defines
the column for the leftmost column of the markdown, and all subsequent markdown should be indented
relative to that column. For example, if the first character of the markdown is in column 16
of the document, then all subsequent markdown lines in that block should also start on column 16.
A bulleted list would start on column 16, and its sublist would be indented four space to column 20.
</para>
</doc:description>
</xs:appinfo>
</xs:annotation>
Expand Down

0 comments on commit c70fcf0

Please sign in to comment.