1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
/*!
* A very simple document model and set of markup wriers.
*
* This crate provides a simple document [`model`](model/index.html) that captures structure of simple documents. This is
* not an all-purpose model, it does not have the richness of full document systems but is intended
* for tools that simply need to generate useful documentation or reports.
*
* The model can then be serialized into specific formats using the formatters in the [`write`](write/index.html)
* module. Currently various flavors of Markdown are implemented as well as the XWiki format.
*
* ## Model
*
* The `somedoc::model` module provides the model to construct documents.
*
* ### Example
*
* ```rust
* use somedoc::model::block::{HasBlockContent, Heading, List, Paragraph};
* use somedoc::model::document::Document;
* use somedoc::model::inline::{HasInlineContent, HyperLink, Image, Span};
*
* fn readme_maker(crate_name: &str, repo_owner: &str, repo_name: &str, headline: &str) -> Document {
* let tbd = Paragraph::plain_str("TBD");
* let mut doc = Document::default();
*
* doc.add_heading(Heading::section(&format!("Crate {}", crate_name)))
* .add_paragraph(Paragraph::plain_str(headline));
*
* let mut para = Paragraph::default();
* para.add_image(Image::with_alt_text(
* "https://img.shields.io/badge/license-mit-118811.svg",
* "MIT License",
* ))
* .add_image(Image::with_alt_text(
* "https://img.shields.io/badge/Min%20Rust-1.40-green.svg",
* "Build",
* ))
* .add_image(Image::with_alt_text(
* &format!(
* "https://github.com/{}/{}/workflows/Rust/badge.svg",
* repo_owner, repo_name
* ),
* "Minimum Rust Version",
* ))
* .add_image(Image::with_alt_text(
* &format!(
* "https://github.com/{}/{}/workflows/Security%20audit/badge.svg",
* repo_owner, repo_name
* ),
* "Audit",
* ));
*
* doc.add_paragraph(para)
* .add_thematic_break()
* .add_paragraph(tbd.clone())
* .add_heading(Heading::sub_section("Example"))
* .add_paragraph(tbd.clone())
* .add_heading(Heading::sub_section("Features"))
* .add_paragraph(tbd.clone())
* .add_thematic_break()
* .add_heading(Heading::sub_section("Changes"))
* .add_paragraph(Paragraph::bold_str("Version 0.1.0"));
*
* let mut list = List::default();
* list.add_item_from(Span::plain_str("Initial release.").into());
*
* doc.add_list(list)
* .add_heading(Heading::sub_section("Issues"))
* .add_paragraph(tbd.clone());
*
* doc
* }
* ```
*
* ## Writers
*
* The `somedoc::write` module contains a number of serializers that generate specific markup for
* different platforms [`html`](html/index.html), [`json`](json/index.html),
* [`latex`](latex/index.html), and [`markdown`](markdown/index.html).
*
* The JSON module is rather different from the rest, it is intended for tool usage and is a
* direct representation of the `Document` model so that other tools may consume it. To read this
* format the [`read`](read/index.html) module provides for parsing from a string value of from
* a `std::io::Read` implementation.
*
* ### Examples
*
* The following writes a constructed document to `stdout` as a Markdown document. The default
* flavor supported by the writer is the [CommonMark](https://spec.commonmark.org/0.29/) spec.
*
* ```rust
* # use somedoc::model::Document;
* use somedoc::write::write_document_to_string;
* use somedoc::write::markdown::MarkdownFlavor;
*
* # fn make_some_document() -> Document { Document::default() }
* let doc = make_some_document();
*
* let doc_str = write_document_to_string(&doc, MarkdownFlavor::default().into()).unwrap();
* println!("{}", doc_str);
* ```
*
* The following writes the same document out in the
* [XWiki](https://www.xwiki.org/xwiki/bin/view/Documentation/UserGuide/Features/XWikiSyntax/)
* markup format.
*
* ```rust
* # use somedoc::model::Document;
* use somedoc::write::{write_document_to_string, OutputFormat};
* use somedoc::write::markdown::MarkdownFlavor;
*
* # fn make_some_document() -> Document { Document::default() }
* let doc = make_some_document();
*
* let doc_str = write_document_to_string(&doc, MarkdownFlavor::XWiki.into()).unwrap();
* println!("{}", doc_str);
* ```
*
* ```rust
* # use somedoc::model::Document;
* use somedoc::write::{write_document_to_string, OutputFormat};
*
* # fn make_some_document() -> Document { Document::default() }
* let doc = make_some_document();
*
* let doc_str = write_document_to_string(&doc, OutputFormat::Html).unwrap();
* println!("{}", doc_str);
* ```
*
* ## Features
*
* * Formats:
* * **fmt_html** - HTML writer.
* * **fmt_latex** - LaTeX (experimental) writer.
* * **fmt_markdown** - Markdown/wiki writer.
* * **emoji_names**; adds a new module `emoji_names` to `model::inline` which only contains string
* constants for commonly supported emoji names. These can then be used to construct `Emoji` values
* for inline characters. This feature is not included by default.
* * **math_builder**; - experimental support for building math expressions. This feature is not
* included by default.
*/
// ------------------------------------------------------------------------------------------------
// Preamble
// ------------------------------------------------------------------------------------------------
extern crate error_chain;
extern crate lazy_static;
// ------------------------------------------------------------------------------------------------
// Modules
// ------------------------------------------------------------------------------------------------