glyph 0.1.0
Sign up to get free protection for your applications and to get access to all the features.
- data/README.textile +80 -0
- data/Rakefile +51 -0
- data/VERSION +1 -0
- data/bin/glyph +7 -0
- data/book/config.yml +5 -0
- data/book/document.glyph +55 -0
- data/book/images/glyph.png +0 -0
- data/book/images/glyph.svg +351 -0
- data/book/lib/macros/reference.rb +98 -0
- data/book/output/html/glyph.html +1809 -0
- data/book/output/html/images/glyph.png +0 -0
- data/book/output/html/images/glyph.svg +351 -0
- data/book/output/pdf/glyph.pdf +4277 -0
- data/book/snippets.yml +13 -0
- data/book/styles/css3.css +220 -0
- data/book/styles/default.css +190 -0
- data/book/text/authoring.textile +351 -0
- data/book/text/extending.textile +148 -0
- data/book/text/getting_started.textile +152 -0
- data/book/text/introduction.textile +88 -0
- data/book/text/ref_commands.textile +74 -0
- data/book/text/ref_config.textile +0 -0
- data/book/text/ref_macros.textile +256 -0
- data/book/text/troubleshooting.textile +118 -0
- data/config.yml +63 -0
- data/document.glyph +29 -0
- data/glyph.gemspec +138 -0
- data/lib/glyph.rb +128 -0
- data/lib/glyph/commands.rb +124 -0
- data/lib/glyph/config.rb +152 -0
- data/lib/glyph/document.rb +145 -0
- data/lib/glyph/glyph_language.rb +530 -0
- data/lib/glyph/glyph_language.treetop +27 -0
- data/lib/glyph/interpreter.rb +84 -0
- data/lib/glyph/macro.rb +69 -0
- data/lib/glyph/node.rb +126 -0
- data/lib/glyph/system_extensions.rb +77 -0
- data/macros/common.rb +66 -0
- data/macros/filters.rb +69 -0
- data/macros/html/block.rb +119 -0
- data/macros/html/inline.rb +43 -0
- data/macros/html/structure.rb +138 -0
- data/spec/files/container.textile +5 -0
- data/spec/files/document.glyph +2 -0
- data/spec/files/document_with_toc.glyph +3 -0
- data/spec/files/included.textile +4 -0
- data/spec/files/ligature.jpg +449 -0
- data/spec/files/markdown.markdown +8 -0
- data/spec/files/test.sass +2 -0
- data/spec/lib/commands_spec.rb +83 -0
- data/spec/lib/config_spec.rb +79 -0
- data/spec/lib/document_spec.rb +100 -0
- data/spec/lib/glyph_spec.rb +76 -0
- data/spec/lib/interpreter_spec.rb +90 -0
- data/spec/lib/macro_spec.rb +60 -0
- data/spec/lib/node_spec.rb +76 -0
- data/spec/macros/filters_spec.rb +42 -0
- data/spec/macros/macros_spec.rb +159 -0
- data/spec/spec_helper.rb +92 -0
- data/spec/tasks/generate_spec.rb +31 -0
- data/spec/tasks/load_spec.rb +37 -0
- data/spec/tasks/project_spec.rb +41 -0
- data/styles/css3.css +220 -0
- data/styles/default.css +190 -0
- data/tasks/generate.rake +57 -0
- data/tasks/load.rake +55 -0
- data/tasks/project.rake +33 -0
- metadata +192 -0
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
|
|
2
|
+
macro :error_table do
|
|
3
|
+
%{
|
|
4
|
+
<table style="width:100%;">
|
|
5
|
+
<tr>
|
|
6
|
+
<th style="width:30%">Error Message</th>
|
|
7
|
+
<th>Description</th>
|
|
8
|
+
</tr>
|
|
9
|
+
#{@value}
|
|
10
|
+
</table>
|
|
11
|
+
}
|
|
12
|
+
end
|
|
13
|
+
|
|
14
|
+
macro :ref_error do
|
|
15
|
+
error, description = @params
|
|
16
|
+
%{
|
|
17
|
+
<tr>
|
|
18
|
+
<td>#{error}</td>
|
|
19
|
+
<td>#{description}</td>
|
|
20
|
+
</tr>
|
|
21
|
+
}
|
|
22
|
+
end
|
|
23
|
+
|
|
24
|
+
macro :"%>" do
|
|
25
|
+
interpret "=>[#m_#@value|#@value] macro"
|
|
26
|
+
end
|
|
27
|
+
|
|
28
|
+
macro :"#>" do
|
|
29
|
+
interpret "=>[#c_#@value|#@value] command"
|
|
30
|
+
end
|
|
31
|
+
|
|
32
|
+
macro :"$>" do
|
|
33
|
+
val = @value.gsub /\./, "_"
|
|
34
|
+
interpret "=>[#s_#{val}|#@value] setting"
|
|
35
|
+
end
|
|
36
|
+
|
|
37
|
+
macro :"parameters" do
|
|
38
|
+
interpret %{
|
|
39
|
+
section[header[#{@name.to_s[0..0].upcase+@name.to_s[1..@name.to_s.length-1]}]
|
|
40
|
+
|
|
41
|
+
<table style="width:100%;">
|
|
42
|
+
<tr>
|
|
43
|
+
<th style="width:30%">#{@name.to_s[0..0].upcase+@name.to_s[1..@name.to_s.length-2]}</th>
|
|
44
|
+
<th>Description</th>
|
|
45
|
+
</tr>
|
|
46
|
+
#{@value}
|
|
47
|
+
</table>
|
|
48
|
+
]
|
|
49
|
+
}
|
|
50
|
+
end
|
|
51
|
+
|
|
52
|
+
macro :option do
|
|
53
|
+
ident, desc = @params
|
|
54
|
+
%{
|
|
55
|
+
<tr>
|
|
56
|
+
<td><notextile>-#{ident[0..0]} (--#{ident})</notextile></td>
|
|
57
|
+
<td>
|
|
58
|
+
#{desc}
|
|
59
|
+
</td>
|
|
60
|
+
</tr>
|
|
61
|
+
}
|
|
62
|
+
end
|
|
63
|
+
|
|
64
|
+
macro :default do
|
|
65
|
+
%{*Default:* @#@value@}
|
|
66
|
+
end
|
|
67
|
+
|
|
68
|
+
macro :values do
|
|
69
|
+
%{*Possible Values:* @#@value@}
|
|
70
|
+
end
|
|
71
|
+
|
|
72
|
+
macro :example do
|
|
73
|
+
%{*Example:* @#@value@}
|
|
74
|
+
end
|
|
75
|
+
|
|
76
|
+
macro :examples do
|
|
77
|
+
%{
|
|
78
|
+
*Examples:*
|
|
79
|
+
#{@value.split("\n").map{|i| "@#{i}@\n"}.to_s}
|
|
80
|
+
}
|
|
81
|
+
end
|
|
82
|
+
|
|
83
|
+
macro :aliases do
|
|
84
|
+
%{*Aliases:* @#@value@}
|
|
85
|
+
end
|
|
86
|
+
|
|
87
|
+
macro :ref_macro do
|
|
88
|
+
m_name, m_value = @params
|
|
89
|
+
interpret %{
|
|
90
|
+
section[header[@#{m_name}@|m_#{m_name}]
|
|
91
|
+
#{m_value}
|
|
92
|
+
]
|
|
93
|
+
}
|
|
94
|
+
end
|
|
95
|
+
|
|
96
|
+
macro_alias :options => :parameters
|
|
97
|
+
macro_alias '-p' => :ref_error
|
|
98
|
+
macro_alias '-o' => :option
|
|
@@ -0,0 +1,1809 @@
|
|
|
1
|
+
<?xml version="1.0" encoding="utf-8"?>
|
|
2
|
+
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
|
3
|
+
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
|
|
4
|
+
<head>
|
|
5
|
+
<title>Glyph</title>
|
|
6
|
+
<meta name="author" content="Fabio Cevasco" />
|
|
7
|
+
<meta name="copyright" content="Fabio Cevasco" />
|
|
8
|
+
<style type="text/css">
|
|
9
|
+
* {
|
|
10
|
+
border: none;
|
|
11
|
+
font-family: inherit;
|
|
12
|
+
font-size: 100%;
|
|
13
|
+
font-style: inherit;
|
|
14
|
+
margin: 0;
|
|
15
|
+
padding: 0;
|
|
16
|
+
}
|
|
17
|
+
html {
|
|
18
|
+
background: #fff;
|
|
19
|
+
}
|
|
20
|
+
p, ol, ul {
|
|
21
|
+
margin: 0.3em 0;
|
|
22
|
+
}
|
|
23
|
+
table {
|
|
24
|
+
border-collapse: collapse;
|
|
25
|
+
border-spacing: 0;
|
|
26
|
+
margin: auto;
|
|
27
|
+
margin-top: 1em;
|
|
28
|
+
}
|
|
29
|
+
body {
|
|
30
|
+
line-height: 1.2em;
|
|
31
|
+
margin: 0;
|
|
32
|
+
padding: 0;
|
|
33
|
+
padding: 0 1em;
|
|
34
|
+
text-align: justify;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/* Structure */
|
|
38
|
+
.titlepage {
|
|
39
|
+
margin: auto;
|
|
40
|
+
text-align: center;
|
|
41
|
+
}
|
|
42
|
+
.title, h1 {
|
|
43
|
+
font-size: 2.5em;
|
|
44
|
+
font-weight: bold;
|
|
45
|
+
line-height: 1.5em;
|
|
46
|
+
margin-bottom: 0.2em;
|
|
47
|
+
}
|
|
48
|
+
.titlepage h2 {
|
|
49
|
+
font-size: 1.1em;
|
|
50
|
+
font-style: italic;
|
|
51
|
+
font-weight: bold;
|
|
52
|
+
line-height: 1.2em;
|
|
53
|
+
margin-bottom: 0.5em;
|
|
54
|
+
prince-bookmark-level: none;
|
|
55
|
+
}
|
|
56
|
+
.author {
|
|
57
|
+
font-size: 1em;
|
|
58
|
+
}
|
|
59
|
+
.pubdate {
|
|
60
|
+
font-size: 0.8em;
|
|
61
|
+
}
|
|
62
|
+
li {
|
|
63
|
+
list-style-type: square;
|
|
64
|
+
margin: 0.4em 0;
|
|
65
|
+
margin-left: 1.5em;
|
|
66
|
+
}
|
|
67
|
+
ol li{
|
|
68
|
+
list-style-type: decimal;
|
|
69
|
+
}
|
|
70
|
+
img {
|
|
71
|
+
margin: 0 5px;
|
|
72
|
+
padding: 2px;
|
|
73
|
+
}
|
|
74
|
+
dt {
|
|
75
|
+
font-weight: bold;
|
|
76
|
+
margin-top: 1em;
|
|
77
|
+
}
|
|
78
|
+
dd {
|
|
79
|
+
font-style: italic;
|
|
80
|
+
}
|
|
81
|
+
p {
|
|
82
|
+
margin: 1em 0;
|
|
83
|
+
}
|
|
84
|
+
ol.toc {
|
|
85
|
+
margin-left: 1.5em;
|
|
86
|
+
}
|
|
87
|
+
.toc > li[class] {
|
|
88
|
+
font-weight: bold;
|
|
89
|
+
}
|
|
90
|
+
.toc li {
|
|
91
|
+
list-style-type: none;
|
|
92
|
+
margin-left: 0;
|
|
93
|
+
}
|
|
94
|
+
.toc li a, .toc li a:hover {
|
|
95
|
+
color: #000;
|
|
96
|
+
}
|
|
97
|
+
table {
|
|
98
|
+
border: 1px solid #E6E6E6;
|
|
99
|
+
}
|
|
100
|
+
th {
|
|
101
|
+
background: #EEE;
|
|
102
|
+
}
|
|
103
|
+
tr, td, th {
|
|
104
|
+
padding: 5px;
|
|
105
|
+
}
|
|
106
|
+
td, tr {
|
|
107
|
+
border: 1px solid #E6E6E6;
|
|
108
|
+
}
|
|
109
|
+
sup {
|
|
110
|
+
font-size: 0.7em;
|
|
111
|
+
font-weight: bold;
|
|
112
|
+
margin-left: -0.4em;
|
|
113
|
+
}
|
|
114
|
+
/* BLOCKS */
|
|
115
|
+
.center {
|
|
116
|
+
margin: auto;
|
|
117
|
+
text-align: center;
|
|
118
|
+
}
|
|
119
|
+
.left {
|
|
120
|
+
margin: auto;
|
|
121
|
+
text-align: left;
|
|
122
|
+
}
|
|
123
|
+
.right {
|
|
124
|
+
margin: auto;
|
|
125
|
+
text-align: center;
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
.note,
|
|
129
|
+
.important,
|
|
130
|
+
.tip,
|
|
131
|
+
.caution,
|
|
132
|
+
.box {
|
|
133
|
+
border: 1px solid #E6E6E6;
|
|
134
|
+
display: block;
|
|
135
|
+
margin: 0.5em auto;
|
|
136
|
+
padding: 0 0.5em;
|
|
137
|
+
width: 600px;
|
|
138
|
+
background: #EEE;
|
|
139
|
+
color: #1F1F1F;
|
|
140
|
+
}
|
|
141
|
+
.note-title {
|
|
142
|
+
font-weight: bold;
|
|
143
|
+
margin-right: 1em;
|
|
144
|
+
}
|
|
145
|
+
.box-title {
|
|
146
|
+
display: block;
|
|
147
|
+
text-align: center;
|
|
148
|
+
font-weight: bold;
|
|
149
|
+
}
|
|
150
|
+
.code {
|
|
151
|
+
margin: 1em auto;
|
|
152
|
+
padding: 0.5em;
|
|
153
|
+
width: 600px;
|
|
154
|
+
}
|
|
155
|
+
/* TEXT */
|
|
156
|
+
body {
|
|
157
|
+
color: #000;
|
|
158
|
+
font-size: 1em;
|
|
159
|
+
}
|
|
160
|
+
h2 {
|
|
161
|
+
display: block;
|
|
162
|
+
font-size: 2em;
|
|
163
|
+
font-weight: bold;
|
|
164
|
+
margin: 3em 0 1em 0;
|
|
165
|
+
}
|
|
166
|
+
h3 {
|
|
167
|
+
font-size: 1.6em;
|
|
168
|
+
font-weight: normal;
|
|
169
|
+
margin: 3em 0 1em 0;
|
|
170
|
+
}
|
|
171
|
+
h4 {
|
|
172
|
+
font-size: 1.3em;
|
|
173
|
+
font-weight: normal;
|
|
174
|
+
margin: 3em 0 1em 0;
|
|
175
|
+
}
|
|
176
|
+
em {
|
|
177
|
+
font-style: italic;
|
|
178
|
+
}
|
|
179
|
+
a {
|
|
180
|
+
color: #8A1513;
|
|
181
|
+
text-decoration: none;
|
|
182
|
+
}
|
|
183
|
+
a:hover {
|
|
184
|
+
color: #CF282D;
|
|
185
|
+
}
|
|
186
|
+
code {
|
|
187
|
+
font-size: 0.75em;
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
/* FONTS */
|
|
191
|
+
body {
|
|
192
|
+
font-family: "Book Antiqua", "Times New Roman", "Serif";
|
|
193
|
+
}
|
|
194
|
+
|
|
195
|
+
code {
|
|
196
|
+
font-family: "Droid Sans Mono", "Consolas", "Monaco", "Courier", "Monospace";
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
|
|
200
|
+
</style>
|
|
201
|
+
|
|
202
|
+
|
|
203
|
+
<style type="text/css">
|
|
204
|
+
@page {
|
|
205
|
+
size: A4;
|
|
206
|
+
margin: 40pt 30pt 40pt 30pt;
|
|
207
|
+
@top {
|
|
208
|
+
content: string(book-title) " · " string(book-subtitle) " – " string(chapter-title);
|
|
209
|
+
font-style: italic;
|
|
210
|
+
}
|
|
211
|
+
@bottom { content: counter(page, decimal); }
|
|
212
|
+
}
|
|
213
|
+
|
|
214
|
+
@page frontmatter {
|
|
215
|
+
@bottom { content: counter(page, lower-roman); }
|
|
216
|
+
}
|
|
217
|
+
|
|
218
|
+
@page backmatter {
|
|
219
|
+
@bottom { content: counter(page, decimal); }
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
@page:first {
|
|
223
|
+
padding-top: 20%;
|
|
224
|
+
@top { content: normal; }
|
|
225
|
+
@bottom { content: normal; }
|
|
226
|
+
}
|
|
227
|
+
|
|
228
|
+
.toc li a::after {
|
|
229
|
+
content: leader('.') target-counter(attr(href), page);
|
|
230
|
+
}
|
|
231
|
+
|
|
232
|
+
.titlepage h1 {
|
|
233
|
+
string-set: book-title content();
|
|
234
|
+
}
|
|
235
|
+
|
|
236
|
+
.titlepage h2 {
|
|
237
|
+
string-set: book-subtitle content();
|
|
238
|
+
}
|
|
239
|
+
|
|
240
|
+
.toc>li[class~=chapter] {
|
|
241
|
+
counter-increment: toc1;
|
|
242
|
+
counter-reset: toc2;
|
|
243
|
+
}
|
|
244
|
+
|
|
245
|
+
.toc>li[class~=appendix] {
|
|
246
|
+
counter-increment: appendix1;
|
|
247
|
+
counter-reset: toc2;
|
|
248
|
+
}
|
|
249
|
+
|
|
250
|
+
.toc ol li[class] {
|
|
251
|
+
counter-increment: toc2;
|
|
252
|
+
counter-reset: toc3;
|
|
253
|
+
}
|
|
254
|
+
|
|
255
|
+
.toc ol ol li[class] {
|
|
256
|
+
counter-increment: toc3;
|
|
257
|
+
counter-reset: toc4;
|
|
258
|
+
}
|
|
259
|
+
|
|
260
|
+
.toc ol ol ol li[class] {
|
|
261
|
+
counter-increment: toc4;
|
|
262
|
+
counter-reset: toc5;
|
|
263
|
+
}
|
|
264
|
+
|
|
265
|
+
.toc ol ol ol ol li[class] {
|
|
266
|
+
counter-increment: toc5;
|
|
267
|
+
}
|
|
268
|
+
|
|
269
|
+
.toc>li[class~=chapter]::before {
|
|
270
|
+
content: counter(toc1) ". ";
|
|
271
|
+
}
|
|
272
|
+
|
|
273
|
+
|
|
274
|
+
.toc>li[class~=appendix]::before {
|
|
275
|
+
content: counter(appendix1, upper-latin) ". ";
|
|
276
|
+
}
|
|
277
|
+
|
|
278
|
+
.toc>li[class] {
|
|
279
|
+
margin: 1em 0;
|
|
280
|
+
}
|
|
281
|
+
|
|
282
|
+
.toc ol li[class~=bodymatter]::before {
|
|
283
|
+
margin-left: 1em;
|
|
284
|
+
content: counter(toc1) "." counter(toc2) " ";
|
|
285
|
+
}
|
|
286
|
+
.toc ol li[class~=appendix]::before {
|
|
287
|
+
margin-left: 1em;
|
|
288
|
+
content: counter(appendix1, upper-latin) "." counter(toc2) " ";
|
|
289
|
+
}
|
|
290
|
+
|
|
291
|
+
|
|
292
|
+
.toc ol ol li[class~=bodymatter]::before {
|
|
293
|
+
margin-left: 1em;
|
|
294
|
+
content: counter(toc1) "." counter(toc2) "." counter(toc3) " ";
|
|
295
|
+
}
|
|
296
|
+
.toc ol ol li[class~=appendix]::before {
|
|
297
|
+
margin-left: 1em;
|
|
298
|
+
content: counter(appendix1, upper-latin) "." counter(toc2) "." counter(toc3) " ";
|
|
299
|
+
}
|
|
300
|
+
|
|
301
|
+
.toc ol ol ol li[class~=bodymatter]::before {
|
|
302
|
+
margin-left: 1em;
|
|
303
|
+
content: counter(toc1) "." counter(toc2) "." counter(toc3) "." counter(toc4) " ";
|
|
304
|
+
}
|
|
305
|
+
.toc ol ol ol li[class~=appendix]::before {
|
|
306
|
+
margin-left: 1em;
|
|
307
|
+
content: counter(appendix1, upper-latin) "." counter(toc2) "." counter(toc3) "." counter(toc4) " ";
|
|
308
|
+
}
|
|
309
|
+
|
|
310
|
+
.toc ol ol ol ol li[class~=bodymatter]::before {
|
|
311
|
+
margin-left: 1em;
|
|
312
|
+
content: counter(toc1) "." counter(toc2) "." counter(toc3) "." counter(toc4) "." counter(toc5) " ";
|
|
313
|
+
}
|
|
314
|
+
.toc ol ol ol ol li[class~=appendix]::before {
|
|
315
|
+
margin-left: 1em;
|
|
316
|
+
content: counter(appendix1, upper-latin) "." counter(toc2) "." counter(toc3) "." counter(toc4) "." counter(toc5) " ";
|
|
317
|
+
}
|
|
318
|
+
|
|
319
|
+
div.frontmatter{
|
|
320
|
+
page: frontmatter;
|
|
321
|
+
}
|
|
322
|
+
|
|
323
|
+
div.backmatter{
|
|
324
|
+
page: backmatter;
|
|
325
|
+
}
|
|
326
|
+
|
|
327
|
+
.bodymatter h2::before {
|
|
328
|
+
content: "Chapter " counter(h2, upper-roman) " – ";
|
|
329
|
+
counter-reset: footnote;
|
|
330
|
+
}
|
|
331
|
+
|
|
332
|
+
.backmatter h2::before {
|
|
333
|
+
content: "Appendix " counter(a2, upper-latin) " – ";
|
|
334
|
+
}
|
|
335
|
+
|
|
336
|
+
.bodymatter h3::before {
|
|
337
|
+
content: counter(h2) "." counter(h3) " ";
|
|
338
|
+
}
|
|
339
|
+
|
|
340
|
+
.backmatter h3::before {
|
|
341
|
+
content: counter(a2, upper-latin) "." counter(h3) " ";
|
|
342
|
+
}
|
|
343
|
+
|
|
344
|
+
.bodymatter h4::before {
|
|
345
|
+
content: counter(h2) "." counter(h3) "." counter(h4) " ";
|
|
346
|
+
}
|
|
347
|
+
|
|
348
|
+
.backmatter h4::before {
|
|
349
|
+
content: counter(a2, upper-latin) "." counter(h3) "." counter(h4) " ";
|
|
350
|
+
}
|
|
351
|
+
|
|
352
|
+
.bodymatter h5::before {
|
|
353
|
+
content: counter(h2) "." counter(h3) "." counter(h4) "." counter(h5) " ";
|
|
354
|
+
}
|
|
355
|
+
|
|
356
|
+
.backmatter h5::before {
|
|
357
|
+
content: counter(a2, upper-latin) "." counter(h3) "." counter(h4) "." counter(h5) " ";
|
|
358
|
+
}
|
|
359
|
+
|
|
360
|
+
h2 {
|
|
361
|
+
string-set: chapter-title content();
|
|
362
|
+
page-break-before: always;
|
|
363
|
+
}
|
|
364
|
+
|
|
365
|
+
.titlepage h2 {
|
|
366
|
+
page-break-before: avoid;
|
|
367
|
+
}
|
|
368
|
+
|
|
369
|
+
.bodymatter h2{
|
|
370
|
+
counter-increment: h2;
|
|
371
|
+
counter-reset: h3;
|
|
372
|
+
}
|
|
373
|
+
|
|
374
|
+
.backmatter h2{
|
|
375
|
+
counter-increment: a2;
|
|
376
|
+
counter-reset: h3;
|
|
377
|
+
}
|
|
378
|
+
|
|
379
|
+
.bodymatter h3, .backmatter h3 {
|
|
380
|
+
counter-increment: h3;
|
|
381
|
+
counter-reset: h4;
|
|
382
|
+
}
|
|
383
|
+
|
|
384
|
+
.bodymatter h4, .backmatter h4 {
|
|
385
|
+
counter-increment: h4;
|
|
386
|
+
counter-reset: h5;
|
|
387
|
+
}
|
|
388
|
+
|
|
389
|
+
.bodymatter h5, .backmatter h5 {
|
|
390
|
+
counter-increment: h5;
|
|
391
|
+
}
|
|
392
|
+
|
|
393
|
+
h2, h3, h4, h5 { page-break-after: avoid }
|
|
394
|
+
table, .box, .note, .important, .tip, .caution, .code { page-break-inside: avoid }
|
|
395
|
+
|
|
396
|
+
/* Footnotes */
|
|
397
|
+
|
|
398
|
+
@page {
|
|
399
|
+
@footnotes {
|
|
400
|
+
border-top: 1px solid #000;
|
|
401
|
+
}
|
|
402
|
+
}
|
|
403
|
+
|
|
404
|
+
.fn {
|
|
405
|
+
font-size: 85%;
|
|
406
|
+
margin-left: 1.5em;
|
|
407
|
+
display: prince-footnote;
|
|
408
|
+
counter-increment: footnote;
|
|
409
|
+
}
|
|
410
|
+
|
|
411
|
+
.fn::footnote-call {
|
|
412
|
+
content: counter(footnote);
|
|
413
|
+
font-size: 85%;
|
|
414
|
+
vertical-align: super;
|
|
415
|
+
line-height: none;
|
|
416
|
+
font-weight: bold;
|
|
417
|
+
margin-left: 1pt;
|
|
418
|
+
}
|
|
419
|
+
|
|
420
|
+
.fn::footnote-marker {
|
|
421
|
+
font-weight: bold;
|
|
422
|
+
margin-right: 0.5em;
|
|
423
|
+
}
|
|
424
|
+
|
|
425
|
+
</style>
|
|
426
|
+
</head>
|
|
427
|
+
|
|
428
|
+
|
|
429
|
+
<body>
|
|
430
|
+
<div class="titlepage">
|
|
431
|
+
|
|
432
|
+
<img src="images/glyph.svg" width="20%" height="20%" alt="-"/>
|
|
433
|
+
|
|
434
|
+
|
|
435
|
+
<h1>
|
|
436
|
+
Glyph
|
|
437
|
+
</h1>
|
|
438
|
+
|
|
439
|
+
|
|
440
|
+
<h2>
|
|
441
|
+
Rapid Document Authoring Framework
|
|
442
|
+
</h2>
|
|
443
|
+
|
|
444
|
+
v0.1.0
|
|
445
|
+
(draft)
|
|
446
|
+
|
|
447
|
+
<div class="author">
|
|
448
|
+
by <em>Fabio Cevasco</em>
|
|
449
|
+
</div>
|
|
450
|
+
|
|
451
|
+
|
|
452
|
+
<div class="pubdate">
|
|
453
|
+
April 2010
|
|
454
|
+
</div>
|
|
455
|
+
|
|
456
|
+
</div>
|
|
457
|
+
<div class="frontmatter">
|
|
458
|
+
|
|
459
|
+
|
|
460
|
+
<div class="contents">
|
|
461
|
+
<h2 class="toc-header" id="h_toc">Table of Contents</h2>
|
|
462
|
+
<ol class="toc">
|
|
463
|
+
<li class="frontmatter introduction"><a href="#h_1">Introduction</a></li>
|
|
464
|
+
<li class="bodymatter chapter"><a href="#h_7">Getting Started</a></li>
|
|
465
|
+
<li><ol><li class="bodymatter section"><a href="#h_8">Creating your first Glyph Project</a></li>
|
|
466
|
+
<li class="bodymatter section"><a href="#struct">Document Structure</a></li>
|
|
467
|
+
<li class="bodymatter section"><a href="#cfg">Project Configuration</a></li>
|
|
468
|
+
</ol></li>
|
|
469
|
+
<li class="bodymatter chapter"><a href="#h_11">Authoring Documents</a></li>
|
|
470
|
+
<li><ol><li class="bodymatter section"><a href="#h_12">Text Editing</a></li>
|
|
471
|
+
<li><ol><li class="bodymatter section"><a href="#h_13">Introducing Glyph Macros</a></li>
|
|
472
|
+
<li class="bodymatter section"><a href="#esc_quot">Escaping and Quoting</a></li>
|
|
473
|
+
<li class="bodymatter section"><a href="#sec_head">Sections and Headers</a></li>
|
|
474
|
+
<li class="bodymatter section"><a href="#h_16">Including Files and Snippets</a></li>
|
|
475
|
+
<li class="bodymatter section"><a href="#links">Links and Bookmarks</a></li>
|
|
476
|
+
<li class="bodymatter section"><a href="#h_18">Evaluating Ruby code and Configuration Settings</a></li>
|
|
477
|
+
<li class="bodymatter section"><a href="#img_fig">Images and Figures</a></li>
|
|
478
|
+
</ol></li>
|
|
479
|
+
<li class="bodymatter section"><a href="#compile">Compiling your project</a></li>
|
|
480
|
+
<li><ol><li class="bodymatter section"><a href="#stylesheets">Adding Stylesheets</a></li>
|
|
481
|
+
<li class="bodymatter section"><a href="#h_22">HTML output</a></li>
|
|
482
|
+
<li class="bodymatter section"><a href="#h_23">PDF Output</a></li>
|
|
483
|
+
</ol></li>
|
|
484
|
+
</ol></li>
|
|
485
|
+
<li class="bodymatter chapter"><a href="#extending">Extending Glyph</a></li>
|
|
486
|
+
<li><ol><li class="bodymatter section"><a href="#h_25">Anatomy of a Macro</a></li>
|
|
487
|
+
<li class="bodymatter section"><a href="#h_26">Bookmarks and Headers</a></li>
|
|
488
|
+
<li class="bodymatter section"><a href="#h_27">Using Placeholders</a></li>
|
|
489
|
+
<li class="bodymatter section"><a href="#h_28">Interpreting Glyph Code</a></li>
|
|
490
|
+
<li class="bodymatter section"><a href="#h_29">Further Reading</a></li>
|
|
491
|
+
</ol></li>
|
|
492
|
+
<li class="bodymatter chapter"><a href="#h_30">Troubleshooting</a></li>
|
|
493
|
+
<li><ol><li class="bodymatter section"><a href="#h_31">Generic Errors</a></li>
|
|
494
|
+
<li class="bodymatter section"><a href="#h_32">Command Errors</a></li>
|
|
495
|
+
<li class="bodymatter section"><a href="#h_33">Macro Errors</a></li>
|
|
496
|
+
</ol></li>
|
|
497
|
+
<li class="backmatter appendix"><a href="#cmd_ref">Command Reference</a></li>
|
|
498
|
+
<li><ol><li class="appendix section"><a href="#h_35">Global Options</a></li>
|
|
499
|
+
<li><ol><li class="appendix section"><a href="#h_36">-d, --debug</a></li>
|
|
500
|
+
</ol></li>
|
|
501
|
+
<li class="appendix section"><a href="#h_37">add</a></li>
|
|
502
|
+
<li><ol><li class="appendix section"><a href="#h_38">Parameters</a></li>
|
|
503
|
+
</ol></li>
|
|
504
|
+
<li class="appendix section"><a href="#h_39">compile</a></li>
|
|
505
|
+
<li><ol><li class="appendix section"><a href="#h_40">Options</a></li>
|
|
506
|
+
</ol></li>
|
|
507
|
+
<li class="appendix section"><a href="#h_41">config</a></li>
|
|
508
|
+
<li><ol><li class="appendix section"><a href="#h_42">Options</a></li>
|
|
509
|
+
<li class="appendix section"><a href="#h_43">Parameters</a></li>
|
|
510
|
+
</ol></li>
|
|
511
|
+
<li class="appendix section"><a href="#h_44">init</a></li>
|
|
512
|
+
<li class="appendix section"><a href="#c_todo">todo</a></li>
|
|
513
|
+
</ol></li>
|
|
514
|
+
<li class="backmatter appendix"><a href="#macro_ref">Macro Reference</a></li>
|
|
515
|
+
<li><ol><li class="appendix section"><a href="#h_47">Common Macros</a></li>
|
|
516
|
+
<li><ol><li class="appendix section"><a href="#m_comment">comment</a></li>
|
|
517
|
+
<li class="appendix section"><a href="#m_todo">todo</a></li>
|
|
518
|
+
<li class="appendix section"><a href="#m_snippet">snippet</a></li>
|
|
519
|
+
<li class="appendix section"><a href="#m_include">include</a></li>
|
|
520
|
+
<li class="appendix section"><a href="#m_ruby">ruby</a></li>
|
|
521
|
+
<li class="appendix section"><a href="#m_config">config</a></li>
|
|
522
|
+
<li class="appendix section"><a href="#m_escape">escape</a></li>
|
|
523
|
+
</ol></li>
|
|
524
|
+
<li class="appendix section"><a href="#f_macros">Filter Macros</a></li>
|
|
525
|
+
<li><ol><li class="appendix section"><a href="#m_textile">textile</a></li>
|
|
526
|
+
<li class="appendix section"><a href="#m_markdown">markdown</a></li>
|
|
527
|
+
</ol></li>
|
|
528
|
+
<li class="appendix section"><a href="#h_58">Block Macros</a></li>
|
|
529
|
+
<li><ol><li class="appendix section"><a href="#m_note">note</a></li>
|
|
530
|
+
<li class="appendix section"><a href="#m_box">box</a></li>
|
|
531
|
+
<li class="appendix section"><a href="#m_code">code</a></li>
|
|
532
|
+
<li class="appendix section"><a href="#m_title">title</a></li>
|
|
533
|
+
<li class="appendix section"><a href="#m_subtitle">subtitle</a></li>
|
|
534
|
+
<li class="appendix section"><a href="#m_pubdate">pubdate</a></li>
|
|
535
|
+
<li class="appendix section"><a href="#m_img">img</a></li>
|
|
536
|
+
<li class="appendix section"><a href="#m_fig">fig</a></li>
|
|
537
|
+
<li class="appendix section"><a href="#m_table">table</a></li>
|
|
538
|
+
<li class="appendix section"><a href="#m_tr">tr</a></li>
|
|
539
|
+
<li class="appendix section"><a href="#m_th">th</a></li>
|
|
540
|
+
<li class="appendix section"><a href="#m_td">td</a></li>
|
|
541
|
+
</ol></li>
|
|
542
|
+
<li class="appendix section"><a href="#h_71">Inline Macros</a></li>
|
|
543
|
+
<li><ol><li class="appendix section"><a href="#m_anchor">anchor</a></li>
|
|
544
|
+
<li class="appendix section"><a href="#m_link">link</a></li>
|
|
545
|
+
<li class="appendix section"><a href="#m_codeph">codeph</a></li>
|
|
546
|
+
<li class="appendix section"><a href="#m_fmi">fmi</a></li>
|
|
547
|
+
</ol></li>
|
|
548
|
+
<li class="appendix section"><a href="#h_76">Structure Macros</a></li>
|
|
549
|
+
<li><ol><li class="appendix section"><a href="#m_div">div</a></li>
|
|
550
|
+
<li class="appendix section"><a href="#m_header">header</a></li>
|
|
551
|
+
<li class="appendix section"><a href="#m_document">document</a></li>
|
|
552
|
+
<li class="appendix section"><a href="#m_body">body</a></li>
|
|
553
|
+
<li class="appendix section"><a href="#m_head">head</a></li>
|
|
554
|
+
<li class="appendix section"><a href="#m_style">style</a></li>
|
|
555
|
+
<li class="appendix section"><a href="#m_toc">toc</a></li>
|
|
556
|
+
</ol></li>
|
|
557
|
+
</ol></li>
|
|
558
|
+
<li class="backmatter appendix"><a href="#cfg_ref">Configuration Reference</a></li>
|
|
559
|
+
|
|
560
|
+
</ol>
|
|
561
|
+
</div>
|
|
562
|
+
<div class="introduction">
|
|
563
|
+
|
|
564
|
+
<h2 id="h_1">Introduction</h2>
|
|
565
|
+
|
|
566
|
+
<p>Glyph is a <em>Rapid Document Authoring Framework</em>.</p>
|
|
567
|
+
<p>Think of it like a sort of <a href="http://www.rubyonrails.org">Ruby on Rails</a> but for creating text documents instead of web sites. With Glyph, you can manage your documents tidily in <em>projects</em> that can be used to generate deliverables in different formats such as <span class="caps">HTML</span> or <span class="caps">PDF</span> (through <a href="http://www.princexml.com/">Prince</a>).</p>
|
|
568
|
+
<div class="section">
|
|
569
|
+
<h3 id="h_2">Main Features</h3>
|
|
570
|
+
|
|
571
|
+
<p>Glyph uses a <a href="#macros_nutshell">simple macro system</a> to perform a wide variety of advanced tasks:</p>
|
|
572
|
+
<ul>
|
|
573
|
+
<li>Generate block-level <span class="caps">HTML</span> tags not commonly managed by lightweight markups, like <code>head</code>, <code>body</code>, <code>div</code> and <code>table</code>.</li>
|
|
574
|
+
<li>Create and validate internal and external links.</li>
|
|
575
|
+
<li>Include and validate images and figures.</li>
|
|
576
|
+
<li>Automatically determine header levels based on the document structure.</li>
|
|
577
|
+
<li>Automatically generate a Table of Contents based on the document structure.</li>
|
|
578
|
+
<li>Store common snippets of text in a single <span class="caps">YAML</span> file and use them anywhere in your document, as many times as you need.</li>
|
|
579
|
+
<li>Store configuration settings in a <span class="caps">YAML</span> file and use them anywhere in your document, as many times as you need.</li>
|
|
580
|
+
<li>Evaluate Ruby code within your document.</li>
|
|
581
|
+
<li>Call macros from other macros (including snippets), carefully avoiding mutual calls.</li>
|
|
582
|
+
<li>Include text files in other text files.</li>
|
|
583
|
+
<li>Include the contents of configuration settings (author, title) in the document.</li>
|
|
584
|
+
<li>Filter input explicitly or implicitly, based on file extensions when including files.</li>
|
|
585
|
+
<li>Manage comments and todo items.</li>
|
|
586
|
+
</ul>
|
|
587
|
+
</div>
|
|
588
|
+
<div class="section">
|
|
589
|
+
<h3 id="h_3">Installation</h3>
|
|
590
|
+
|
|
591
|
+
<p><code>gem install glyph</code> — simple, as always.</p>
|
|
592
|
+
</div>
|
|
593
|
+
<div class="section">
|
|
594
|
+
<h3 id="h_4">Essential Glyph commands</h3>
|
|
595
|
+
|
|
596
|
+
<p>Glyph is 100% command line. Its interface resambles <a href="http://git-scm.com/">Git’s</a> for its simplicity and power (thanks to the <a href="http://github.com/davetron5000/gli">Gli</a> gem). Here are some example commands:</p>
|
|
597
|
+
<ul>
|
|
598
|
+
<li><code>glyph init</code> — to initialize a new Glyph project in the current (empty) directory.</li>
|
|
599
|
+
<li><code>glyph add introduction.textile</code> — to create a new file called <em>introduction.textile</em>.</li>
|
|
600
|
+
<li><code>glyph compile</code> — to compile the current document into a single <span class="caps">HTML</span> file.</li>
|
|
601
|
+
<li><code>glyph compile -f pdf</code> — to compile the current document into <span class="caps">HTML</span> and then transform it into <span class="caps">PDF</span> using <a href="http://www.princexml.com/">Prince</a>.</li>
|
|
602
|
+
</ul>
|
|
603
|
+
</div>
|
|
604
|
+
<div class="section">
|
|
605
|
+
<h3 id="macros_nutshell">Glyph macros in a nutshell</h3>
|
|
606
|
+
|
|
607
|
+
<p>Format your documents using Textile or Markdown, and use Glyph Macros to do everything else:</p>
|
|
608
|
+
<p><b>Glyph Source:</b></p>
|
|
609
|
+
<div class="code"><pre><code>
|
|
610
|
+
section[header[Something about Glyph]
|
|
611
|
+
You can use Glyph macros in conjunction
|
|
612
|
+
with _Textile_ or _Markdown_ to
|
|
613
|
+
produce HTML files effortlessly.
|
|
614
|
+
section[header[What about PDFs?|pdf]
|
|
615
|
+
Once you have a single, well-formatted HTML
|
|
616
|
+
file, converting it to PDF is
|
|
617
|
+
extremely easy with a 3rd-party
|
|
618
|
+
renderer like =&gt;[http://www.princexml.com|Prince].
|
|
619
|
+
]
|
|
620
|
+
]
|
|
621
|
+
</code></pre></div>
|
|
622
|
+
<p><b><span class="caps">HTML</span> Output:</b></p>
|
|
623
|
+
<div class="code"><pre><code>
|
|
624
|
+
<div class="section">
|
|
625
|
+
<h2 id="h_10">Something about Glyph</h2>
|
|
626
|
+
<p>You can use Glyph macros in conjunction with
|
|
627
|
+
<em>Textile</em> or <em>Markdown</em> to
|
|
628
|
+
produce HTML files effortlessly.</p>
|
|
629
|
+
<div class="section">
|
|
630
|
+
<h3 id="pdf">What about PDFs?</h3>
|
|
631
|
+
<p>Once you have a single, well-formatted HTML
|
|
632
|
+
file, converting it to PDF is
|
|
633
|
+
extremely easy with a 3rd-party renderer
|
|
634
|
+
like <a href="http://www.princexml.com">Prince</a>.</p>
|
|
635
|
+
</div>
|
|
636
|
+
</div>
|
|
637
|
+
</code></pre></div></div>
|
|
638
|
+
<div class="section">
|
|
639
|
+
<h3 id="h_6">Resources</h3>
|
|
640
|
+
|
|
641
|
+
<ul>
|
|
642
|
+
<li>Home Page: <a href="http://www.h3rald.com/glyph/">http://www.h3rald.com/glyph/</a></li>
|
|
643
|
+
<li>Repository: <a href="http://www.github.com/h3rald/glyph/">http://www.github.com/h3rald/glyph/</a></li>
|
|
644
|
+
<li>Bug Tracking: <a href="http://www.github.com/h3rald/glyph/issues">http://www.github.com/h3rald/glyph/issues</a></li>
|
|
645
|
+
<li>Book (<span class="caps">PDF</span>): <a href="http://github.com/h3rald/glyph/raw/master/book/output/pdf/glyph.pdf">http://github.com/h3rald/glyph/raw/master/book/output/pdf/glyph.pdf</a></li>
|
|
646
|
+
<li>Reference Documentation: <a href="http://yardoc.org/docs/h3rald-glyph/">http://yardoc.org/docs/h3rald-glyph/</a></li>
|
|
647
|
+
<li>User Group: <a href="http://groups.google.com/group/glyph-framework">http://groups.google.com/group/glyph-framework</a></li>
|
|
648
|
+
</ul>
|
|
649
|
+
</div>
|
|
650
|
+
|
|
651
|
+
</div>
|
|
652
|
+
|
|
653
|
+
</div>
|
|
654
|
+
<div class="bodymatter">
|
|
655
|
+
|
|
656
|
+
<div class="chapter">
|
|
657
|
+
|
|
658
|
+
<h2 id="h_7">Getting Started</h2>
|
|
659
|
+
|
|
660
|
+
<div class="section">
|
|
661
|
+
<h3 id="h_8">Creating your first Glyph Project</h3>
|
|
662
|
+
|
|
663
|
+
<p>To install Glyph, simply run <code>gem install glyph</code>, like with any other Ruby gem. Then, create a new directory and initialize a new Glyph project, like so:</p>
|
|
664
|
+
<p><code>mkdir</code> <em>test_document</em></p>
|
|
665
|
+
<p><code>cd</code> <em>test_document</em></p>
|
|
666
|
+
<p><code>glyph init</code></p>
|
|
667
|
+
<p>That’s it. You just created a new Glyph project in the <code>test_document</code> directory.</p>
|
|
668
|
+
<div class="box"><span class="box-title">Glyph’s dependencies</span><br />
|
|
669
|
+
Glyph requires the following gems:<br />
|
|
670
|
+
- extlib<br />
|
|
671
|
+
- gli<br />
|
|
672
|
+
- treetop<br />
|
|
673
|
+
- rake<br />
|
|
674
|
+
<br />
|
|
675
|
+
Additionally, some Glyph macros may require additional gems, such as:<br />
|
|
676
|
+
- RedCloth (<em>textile</em> macro)<br />
|
|
677
|
+
- Maruku <em>or</em> Kramdown <em>or</em> BlueCloth (<em>markdown</em> macro)<br />
|
|
678
|
+
- Haml (if you want to load .sass files with the <em>style</em> macro) </div>
|
|
679
|
+
<p>Every Glyph project is comprised of the following directories:</p>
|
|
680
|
+
<ul>
|
|
681
|
+
<li><code>images/</code> — used to store the image files used in your document.</li>
|
|
682
|
+
<li><code>lib/</code> — used to store your custom Glyph macros and Rake tasks.</li>
|
|
683
|
+
<li><code>output/</code> — used to store your generated output files.</li>
|
|
684
|
+
<li><code>styles/</code> — used to store your stylesheets.</li>
|
|
685
|
+
<li><code>text/*</code> — used to store your source text files.</li>
|
|
686
|
+
</ul>
|
|
687
|
+
<p>Additionally, the following files are also created at top level:</p>
|
|
688
|
+
<ul>
|
|
689
|
+
<li><code>config.yml</code> — containing your <a href="#cfg">Project Configuration</a>.</li>
|
|
690
|
+
<li><code>document.glyph</code> — containing your <a href="#struct">Document Structure</a></li>
|
|
691
|
+
<li><code>snippets.yml</code> — containing your text snippets.</li>
|
|
692
|
+
</ul>
|
|
693
|
+
</div>
|
|
694
|
+
<div class="section">
|
|
695
|
+
<h3 id="struct">Document Structure</h3>
|
|
696
|
+
|
|
697
|
+
<p>Every Glyph project contains a <code>document.glyph</code> file that is typically used to define the document structure. The default <code>document.glyph</code><br />
|
|
698
|
+
generated automatically when creating a new project is the following:</p>
|
|
699
|
+
<div class="code"><pre><code>
|
|
700
|
+
document[
|
|
701
|
+
head[style[default.css]]
|
|
702
|
+
body[
|
|
703
|
+
titlepage[
|
|
704
|
+
title[]
|
|
705
|
+
author[]
|
|
706
|
+
pubdate[]
|
|
707
|
+
]
|
|
708
|
+
frontmatter[
|
|
709
|
+
toc[]
|
|
710
|
+
preface[header[Preface]
|
|
711
|
+
@[preface.textile]
|
|
712
|
+
]
|
|
713
|
+
]
|
|
714
|
+
bodymatter[
|
|
715
|
+
chapter[header[Chapter #1]
|
|
716
|
+
@[chapter_1.textile]
|
|
717
|
+
]
|
|
718
|
+
chapter[header[Chapter #2]
|
|
719
|
+
@[chapter_2.textile]
|
|
720
|
+
]
|
|
721
|
+
]
|
|
722
|
+
backmatter[
|
|
723
|
+
appendix[header[Appendix A]
|
|
724
|
+
@[appendix_a.textile]
|
|
725
|
+
]
|
|
726
|
+
]
|
|
727
|
+
]
|
|
728
|
+
]
|
|
729
|
+
</code></pre></div>
|
|
730
|
+
<p>Even without knowing anything about Glyph Language, you can easily figure out that this file defines a document with a Table of Contents, a Preface and some Chapters. <code>frontmatter[]</code>, <code>preface[]</code>, <code>chapter[]</code>, etc. are all Glyph <em>macros</em> used to define — in this case — some structural elements. In practice, this means that if you plan to generate an <span class="caps">HTML</span> document, they’ll be converted into <code><div></code> tags.</p>
|
|
731
|
+
<p>Be aware that other macros, on the other hand, are used to do something completely different, e.g.:</p>
|
|
732
|
+
<ul>
|
|
733
|
+
<li><code>toc[]</code> generates the document’s Table of Contents</li>
|
|
734
|
+
<li><code>@[]</code> or its alias <code>include[]</code> is used to copy the contents of another file stored anywhere in the <code>/text</code> directory.</li>
|
|
735
|
+
</ul>
|
|
736
|
+
<p>Let’s now analyze this <code>document.glyph</code> more in detail.</p>
|
|
737
|
+
<ul>
|
|
738
|
+
<li>The <code>document[]</code> macro wraps every other macro. This is necessary to create the initial <code><html></code> tag.</li>
|
|
739
|
+
<li>Similarly, <code>head[]</code> and <code>body[]</code> are used to generate the respective <span class="caps">HTML</span> tags. Actually, <code>head[]</code> already sets some metadata for you, by default (author and copyright).</li>
|
|
740
|
+
<li>Within <code>head[]</code>, the <code>style[]</code> macro is used to load the <code>default.css</code> stylesheet, which is included by default the <code>/styles</code> directory of every Glyph project.</li>
|
|
741
|
+
<li>Immediately after the <code>body[]</code> macro, the <code>titlepage[]</code> macro is used to define (guess…) the first page of your document. <code>title[]</code>, <code>author[]</code> and <code>pubdate[]</code> insert the title of the document, its author and the publication date (retrieved from the project’s <a href="#cfg">configuration settings</a>).</li>
|
|
742
|
+
<li>Then, the <code>frontmatter[]</code>, <code>bodymatter[]</code> and <code>backmatter[]</code> macros are used to further divide the portions of your document according to the rules of <a href="http://en.wikipedia.org/wiki/Book_design">book design</a>. They are not mandatory, but they can be used, for example, to number your appendixes with letters instead of numbers and similar.</li>
|
|
743
|
+
<li><code>preface[]</code>, <code>chapter[]</code>, <code>appendix[]</code> are just a way to wrap content in <code><div></code> tags, from an <span class="caps">HTML</span> point of view, but they are also necessary to nest the content of your document and generate the Table of Contents automatically, together with the <code>header[]</code> macro.</li>
|
|
744
|
+
</ul>
|
|
745
|
+
</div>
|
|
746
|
+
<div class="section">
|
|
747
|
+
<h3 id="cfg">Project Configuration</h3>
|
|
748
|
+
|
|
749
|
+
<p>Glyph stores configuration settings in the following <span class="caps">YAML</span> files:</p>
|
|
750
|
+
<ol>
|
|
751
|
+
<li>Your <em>Project Configuration</em> is stored in the <code>config.yml</code> file, included in each Glyph Project.</li>
|
|
752
|
+
<li>Your <em>Global Configuration</em> is stored in a <code>.glyphrc</code> file in your $<span class="caps">HOME</span> (or %HOMEPATH% on Windows) directory (not created by default).</li>
|
|
753
|
+
<li>The <em>System Configuration</em> is stored in the source directory of Glyph itself.</li>
|
|
754
|
+
</ol>
|
|
755
|
+
<p>When compiling, Glyph loads all these configuration files and merges them according to the following rules:</p>
|
|
756
|
+
<ul>
|
|
757
|
+
<li>A setting configured in the <em>Project Configuration</em> overrides the same setting in both Global and System configuration.</li>
|
|
758
|
+
<li>A setting configured in the <em>Global Configuration</em> overrides the same setting in the <em>System Configuration</em></li>
|
|
759
|
+
</ul>
|
|
760
|
+
<p>Typically, you should use the <em>Project Configuration</em> for all project-specific settings and the <em>Global Configuration</em> for settings affecting all your projects (for example, you may want to set ‘document.author’ in the Global Configuration instead of setting it in the Project Configuration of all your Glyph projects). The <em>System Configuration</em> is best left untouched.</p>
|
|
761
|
+
<p>Instead of editing your configuration settings directly, you can use the <code>glyph config</code> command, as follows:</p>
|
|
762
|
+
<p><code>glyph config</code> <em>setting</em> <em>[value]</em></p>
|
|
763
|
+
<p>If no <em>value</em> is specified, glyph just prints the value of the configuration setting, so typing <code>glyph config document.author</code> right after creating a project (assuming you didn’t set this in the Global Configuration) will print nothing, because this setting is blank by default.</p>
|
|
764
|
+
<p>To change the value of a configuration setting, specify a value right after the setting, like this:</p>
|
|
765
|
+
<p><code>glyph config document.author "John Smith"</code></p>
|
|
766
|
+
<p>In this way, the document author will be set to <em>John Smith</em> for the current project. To save this setting globally, add a <code>-g</code> option, like this:</p>
|
|
767
|
+
<p><code>glyph config -g document.author "John Smith"</code></p>
|
|
768
|
+
<div class="box"><span class="box-title">Regarding configuration values and data types…</span><br />
|
|
769
|
+
Glyph attempts to “guess” the data type of a configuration values by evaluation (<code>Kernel#instance_eval</code>) if the value:<br />
|
|
770
|
+
- is wrapped in quotes (<code>"</code> or <code>'</code>) → String<br />
|
|
771
|
+
- starts with a colon (<code>:</code>) → Symbol<br />
|
|
772
|
+
- is wrapped in square brackets (<code>[</code> and <code>]</code>) → Array<br />
|
|
773
|
+
- is wrapped in curly brackets (<code>\{</code> and <code>\}</code>) → Hash<br />
|
|
774
|
+
- is <em>true</em> or <em>false</em> → Boolean<br />
|
|
775
|
+
- If the value is <em>nil</em> → NilClass<br />
|
|
776
|
+
<br />
|
|
777
|
+
Note that this guessing is far from being foolproof: If you type something like <em>{:test, 2}</em>, for example, you’ll get an error. </div>
|
|
778
|
+
<p>There are plenty of configuration settings that can be modified, but most of them are best if left alone (and in the System Configuration file). For a complete reference, see <a href="#cfg_ref">Configuration Reference</a>. Normally, you may just want to change the following ones:</p>
|
|
779
|
+
<table><tr><th>Setting </th>
|
|
780
|
+
|
|
781
|
+
<th>Description </th>
|
|
782
|
+
</tr>
|
|
783
|
+
|
|
784
|
+
<tr><td><strong>document.author</strong> </td>
|
|
785
|
+
|
|
786
|
+
<td>The author of the document </td>
|
|
787
|
+
</tr>
|
|
788
|
+
|
|
789
|
+
<tr><td><strong>document.title</strong> </td>
|
|
790
|
+
|
|
791
|
+
<td>The title of the document </td>
|
|
792
|
+
</tr>
|
|
793
|
+
|
|
794
|
+
<tr><td><strong>document.filename</strong> </td>
|
|
795
|
+
|
|
796
|
+
<td>The document file name </td>
|
|
797
|
+
</tr>
|
|
798
|
+
</table>
|
|
799
|
+
</div>
|
|
800
|
+
|
|
801
|
+
</div>
|
|
802
|
+
<div class="chapter">
|
|
803
|
+
|
|
804
|
+
<h2 id="h_11">Authoring Documents</h2>
|
|
805
|
+
|
|
806
|
+
<div class="section">
|
|
807
|
+
<h3 id="h_12">Text Editing</h3>
|
|
808
|
+
|
|
809
|
+
<p>One of the aims of Glyph is streamlining text editing. Glyph accomplishes this through its own macro language that can be used in conjunction with Textile or Markdown.</p>
|
|
810
|
+
<div class="section">
|
|
811
|
+
<h4 id="h_13">Introducing Glyph Macros</h4>
|
|
812
|
+
|
|
813
|
+
<p>By now you probably figured out what a macro looks like: it’s an identifier of some kind that wraps a value or parameters within square brackets. More specifically:</p>
|
|
814
|
+
<ul>
|
|
815
|
+
<li>The macro identifier can contain <em>any</em> character except for: <code>[</code>, <code>]</code>, <code>\</code>, <code>|</code> or spaces.</li>
|
|
816
|
+
<li>The delimiters can be either <code>[</code> and <code>]</code> or <code>[=</code> and <code>=]</code> (<span class="fmi">for more information on differences between delimiters, see <a href="#esc_quot">Escaping and Quoting</a></span>).</li>
|
|
817
|
+
<li>The value can be anything, even other macros. If a macro supports more than one parameter, they must be separated with <code>|</code>. For example, the <code>link</code> (<code>=></code>) macro can take an optional second parameter for the link text: <code>=>[#link_id|This is the link text]</code>.</li>
|
|
818
|
+
</ul>
|
|
819
|
+
</div>
|
|
820
|
+
<div class="section">
|
|
821
|
+
<h4 id="esc_quot">Escaping and Quoting</h4>
|
|
822
|
+
|
|
823
|
+
<p>Glyph doesn’t require any special control characters like LaTeX, and its macro syntax is very straightforward and liberal. This however comes with a price: because square brackets are used as delimiters, you must escape any square bracket in your text with a backslash. That’s not <em>too</em> bad if you think about it, unless you’re writing programming code: in that case, escaping every single square bracket can be painful.</p>
|
|
824
|
+
<p>If a portion of your text contains an excessive amount of square brackets, you may consider using the <code>escape</code> macro (or better, its alias <code>.</code>) with <code>[=</code> and <code>=]</code> as delimiters. By itself, the escape macro doesn’t do anything: it just evaluates to its contents, but the special delimiters act as a quote for any square bracket within them. As a consequence, any macro within <code>[=</code> and <code>=]</code> will <em>not</em> be evaluated.</p>
|
|
825
|
+
<p>You can use the quoting delimiters with <em>any</em> macro identifier. Obviously, using them as delimiters for things like <code>section</code> macros may not be a good idea, but they should really be mandatory with the <code>code</code> macro, like this:</p>
|
|
826
|
+
<div class="code"><pre><code>
|
|
827
|
+
code[=
|
|
828
|
+
section[header[A section]
|
|
829
|
+
|
|
830
|
+
This is a section.
|
|
831
|
+
|
|
832
|
+
section[header[A nested section]
|
|
833
|
+
This is another section.
|
|
834
|
+
]
|
|
835
|
+
]
|
|
836
|
+
=]
|
|
837
|
+
</code></pre></div>
|
|
838
|
+
<div class="note"><span class="note-title">Note</span>Although quoting delimiters allow you to use square brackets without escaping them, you must still escape them if you want to escape quoting delimiter themselves. </div>
|
|
839
|
+
<p>Besides square brackets, there are other characters that must or can be escaped with backslashes, as shown in the following table</p>
|
|
840
|
+
<table><tr><th>Escape Sequence </th>
|
|
841
|
+
|
|
842
|
+
<th>Evaluates to… </th>
|
|
843
|
+
|
|
844
|
+
<th>Notes </th>
|
|
845
|
+
</tr>
|
|
846
|
+
|
|
847
|
+
<tr><td><code>\[</code> </td>
|
|
848
|
+
|
|
849
|
+
<td><code>[</code> </td>
|
|
850
|
+
|
|
851
|
+
<td>Square brackets must be escaped unless used as macro delimiters or within a quoting macro. </td>
|
|
852
|
+
</tr>
|
|
853
|
+
|
|
854
|
+
<tr><td><code>\]</code> </td>
|
|
855
|
+
|
|
856
|
+
<td><code>]</code> </td>
|
|
857
|
+
|
|
858
|
+
<td>Square brackets must be escaped unless used as macro delimiters or within a quoting macro. </td>
|
|
859
|
+
</tr>
|
|
860
|
+
|
|
861
|
+
<tr><td><code>\\</code> </td>
|
|
862
|
+
|
|
863
|
+
<td><code>\</code> </td>
|
|
864
|
+
|
|
865
|
+
<td>Backslashes do not have to be escaped by default, but an escaped backslash will evaluate to itself. </td>
|
|
866
|
+
</tr>
|
|
867
|
+
|
|
868
|
+
<tr><td><code>\=</code> </td>
|
|
869
|
+
|
|
870
|
+
<td><code>=</code> </td>
|
|
871
|
+
|
|
872
|
+
<td>Equal signs do not have to be escaped by default, but an escaped equal sign will evaluate to iself. </td>
|
|
873
|
+
</tr>
|
|
874
|
+
|
|
875
|
+
<tr><td><code>\|</code> </td>
|
|
876
|
+
|
|
877
|
+
<td><code>|</code> </td>
|
|
878
|
+
|
|
879
|
+
<td>Pipes must be escaped (even within quoting macros) unless they are used to separate two or more macro parameters. </td>
|
|
880
|
+
</tr>
|
|
881
|
+
|
|
882
|
+
<tr><td><code>\.</code> </td>
|
|
883
|
+
|
|
884
|
+
<td>
|
|
885
|
+
</td>
|
|
886
|
+
|
|
887
|
+
<td>An escaped dot evaluates to nothing. Useful to separate macro identifiers from other characters:<br />
|
|
888
|
+
<code>_=>[#link|This is an emphasized link]_</code> </td>
|
|
889
|
+
</tr>
|
|
890
|
+
</table>
|
|
891
|
+
</div>
|
|
892
|
+
<div class="section">
|
|
893
|
+
<h4 id="sec_head">Sections and Headers</h4>
|
|
894
|
+
|
|
895
|
+
<p>Glyph documents are normally organized as a hierarchical tree of nested chapters, appendixes, sections, etc. To define a section, use the <code>section</code> macro, like so:</p>
|
|
896
|
+
<div class="code"><pre><code>
|
|
897
|
+
section[
|
|
898
|
+
header[Section #1]
|
|
899
|
+
|
|
900
|
+
Write the section contents here...
|
|
901
|
+
|
|
902
|
+
section[
|
|
903
|
+
header[Section #2]
|
|
904
|
+
|
|
905
|
+
This section is nested into the previous one.
|
|
906
|
+
|
|
907
|
+
] --[End of Section #2]
|
|
908
|
+
] --[End of Section #1]
|
|
909
|
+
</code></pre></div>
|
|
910
|
+
<p>This example defines two nested sections, each with its own header. The header is <em>mandatory</em>: it will be displayed at the start of the section and in the Table of Contents.</p>
|
|
911
|
+
<p>Note an important difference from <span class="caps">HTML</span>: there is no explicit level for the headers, as it will be determined at runtime when the document is compiled, based on how sections are nested. The previous code snippet (taken as it is), for example, will be transformed into the following <span class="caps">HTML</span> code:</p>
|
|
912
|
+
<div class="code"><pre><code>
|
|
913
|
+
<div class="section">
|
|
914
|
+
<h2>Section #1</h2>
|
|
915
|
+
<p>Write the section contents here...</p>
|
|
916
|
+
<div class="section">
|
|
917
|
+
<h3>Section #2</h3>
|
|
918
|
+
<p>This section is nested in the previous one</p>
|
|
919
|
+
</div>
|
|
920
|
+
</div>
|
|
921
|
+
</code></pre></div>
|
|
922
|
+
<p>By default, in Glyph the first header level is <em>2</em>, so the two headers are rendered as <code>h2</code> and <code>h3</code>, respectively (<code>--[...]</code> macros are <em>comments</em>, therefore they are not included in the final output).</p>
|
|
923
|
+
<p>There are <em>a lot</em> of macros that can be used in the same way as <code>section</code>, one for each element of <a href="http://en.wikipedia.org/wiki/Book_design">Book Design</a>. Each one of them is a simple wrapper for a <code><div></code> tag with a class set to its name.</p>
|
|
924
|
+
<p>The following table lists the identifiers of all section-like macros, divided according to the part of the book they should be placed in:</p>
|
|
925
|
+
<table><tr><td><strong>Frontmatter</strong> </td>
|
|
926
|
+
|
|
927
|
+
<td><code>imprint</code> <sup>†</sup>, <code>dedication</code> <sup>†</sup>, <code>inspiration</code> <sup>†</sup>, <code>foreword</code> <sup>‡</sup>, <code>introduction</code> <sup>‡</sup>, <code>acknowledgement</code> <sup>‡</sup>, <code>prologue</code> <sup>‡</sup>, <code>toc</code> <sup>*</sup> </td>
|
|
928
|
+
</tr>
|
|
929
|
+
|
|
930
|
+
<tr><td><strong>Bodymatter</strong> </td>
|
|
931
|
+
|
|
932
|
+
<td><code>volume</code>, <code>book</code>, <code>part</code>, <code>chapter</code> </td>
|
|
933
|
+
</tr>
|
|
934
|
+
|
|
935
|
+
<tr><td><strong>Backmatter</strong> </td>
|
|
936
|
+
|
|
937
|
+
<td><code>epilogue</code> <sup>‡</sup>, <code>afterword</code> <sup>‡</sup>, <code>postscript</code> <sup>†</sup>, <code>appendix</code>, <code>addendum</code> <sup>‡</sup>, <code>glossary</code> <sup>**‡</sup>, <code>colophon</code> <sup>†</sup>, <code>bibliography</code> <sup>**‡</sup>, <code>promotion</code> <sup>†</sup>, <code>references</code> <sup>**‡</sup>, <code>index</code> <sup>**‡</sup>, <code>lot</code> <sup>**‡</sup>, <code>lof</code> <sup>**‡</sup> </td>
|
|
938
|
+
</tr>
|
|
939
|
+
</table>
|
|
940
|
+
|
|
941
|
+
<p>*: The <code>toc</code> macro is to generate the Table of Contents automatically, and it must be used with no contents (<code>toc[]</code>).</p>
|
|
942
|
+
<p>**: This macro is likely to be extended in future versions to generate/aggregate content automatically.</p>
|
|
943
|
+
<p>†: This section is not listed in the Table of Contents.</p>
|
|
944
|
+
<p>‡: Any subsection of this section is not listed in the Table of Contents.</p>
|
|
945
|
+
<div class="note"><span class="note-title">Note</span><code>frontmatter</code>, <code>bodymatter</code> and <code>backmatter</code> are also valid (and mandatory!) macro identifiers, typically already included in the default <code>document.glyph</code> file of every project. </div>
|
|
946
|
+
</div>
|
|
947
|
+
<div class="section">
|
|
948
|
+
<h4 id="h_16">Including Files and Snippets</h4>
|
|
949
|
+
|
|
950
|
+
<p>If you’re authoring a user manual, a long article or a book, writing everything inside a single file (<code>document.glyph</code>) may not be optimal. For this reason, Glyph provides an <code>include</code> macro (aliased by <code>@</code>) that can be used to include the contents of any file within the <code>text/</code> directory:</p>
|
|
951
|
+
<p><code>@[introduction.textile]</code></p>
|
|
952
|
+
<p>The macro above loads the contents of the <code>introduction.textile</code> file, that can be stored <em>anywhere</em> within the <code>text/</code> directory.</p>
|
|
953
|
+
<div class="note"><span class="note-title">Note</span>Unlike with <a href="img_fig">image and figures</a> that must be included with their <em>relative</em> path to the <code>images/</code> folder, you must not specify a relative path when including text files. This is due to the fact that images are copied <em>as they are</em> in the <code>output/<format>/images/</code> directory and they have to be linked from the output file.<br />
|
|
954
|
+
<br />
|
|
955
|
+
A possible downside of this behavior is that file names must be unique within the entire <code>text/</code> directory (or any of its subdirectories) </div>
|
|
956
|
+
<p>When including a text file, by default an input filter macro is applied to its contents based on the file extension used:</p>
|
|
957
|
+
<ul>
|
|
958
|
+
<li><code>.textile</code> → <code>textile</code></li>
|
|
959
|
+
<li><code>.markdown</code> or <code>.md</code> → <code>markdown</code></li>
|
|
960
|
+
</ul>
|
|
961
|
+
<div class="tip"><span class="note-title">Tip</span>You can override this behavior by setting the <code>filters.by_file_extensions</code> configuration setting to <code>false</code>, like this:<br />
|
|
962
|
+
<br />
|
|
963
|
+
<code>glyph config filters.by_file_extensions false</code> </div>
|
|
964
|
+
<p>While including the context of an entire file is definitely a useful feature for content reuse, sometimes it can be an overkill. What if, for example, you just want to reuse a short procedure or even a sentence? In this case, you may want to consider using a <em>snippet</em> instead.</p>
|
|
965
|
+
<p>Snippets are text strings saved in <span class="caps">YAML</span> format in the <code>snippets.yml</code> file. They can be included anywhere in your document using the <code>snippet</code> macro (or its alias <code>&</code>).</p>
|
|
966
|
+
<div class="box"><span class="box-title">Example</span><br />
|
|
967
|
+
Consider the following <code>snippets.yml</code> file:<br />
|
|
968
|
+
<div class="code"><pre><code>
|
|
969
|
+
---
|
|
970
|
+
:glang: Glyph Language
|
|
971
|
+
:macros: Glyph Macros
|
|
972
|
+
:sq_esc: |-
|
|
973
|
+
Square brackets must be escaped
|
|
974
|
+
unless used as macro delimiters or within a quoting macro.
|
|
975
|
+
:markups: Textile or Markdown
|
|
976
|
+
:test: |-
|
|
977
|
+
This is a
|
|
978
|
+
Test snippet
|
|
979
|
+
</code></pre></div>
|
|
980
|
+
<p>You can use <code>&[markups]</code> anywhere in your document instead of having to type “Textile or Markdown” every time. Additionally, later on you can change the value of the <code>markups</code> snippets only in the <code>snippets.yml</code> file to change it everywhere else in the document.</p>
|
|
981
|
+
</div>
|
|
982
|
+
<div class="tip"><span class="note-title">Tip</span>Snippets (or any other macro) can be nested within other snippets. Glyph takes care of checking if you nested snippets or macros mutually and warns you if necessary. </div>
|
|
983
|
+
</div>
|
|
984
|
+
<div class="section">
|
|
985
|
+
<h4 id="links">Links and Bookmarks</h4>
|
|
986
|
+
|
|
987
|
+
<p>Lightweight markups let you create internal and external links in a very easy way, and you can still do so in Glyph. However, if you do so:</p>
|
|
988
|
+
<ul>
|
|
989
|
+
<li>There is no built-in way to check if they are valid</li>
|
|
990
|
+
<li>There is no built-in way to determine the title of a link automatically</li>
|
|
991
|
+
</ul>
|
|
992
|
+
<p>If you care about link validation and you want to save some keystrokes, then you should use the following markup-agnostic Glyph Macros:</p>
|
|
993
|
+
<ul>
|
|
994
|
+
<li><code>link</code> (aliased to <code>=></code>) — to create internal and external links.</li>
|
|
995
|
+
<li><code>anchor</code> (aliased to <code>#</code>) — to create named anchors (bookmarks) within your document.</li>
|
|
996
|
+
</ul>
|
|
997
|
+
<div class="box"><span class="box-title">Example</span><br />
|
|
998
|
+
The following Glyph code:<br />
|
|
999
|
+
<br />
|
|
1000
|
+
<div class="code"><pre><code>
|
|
1001
|
+
This is a link to =&gt;[#test].
|
|
1002
|
+
|
|
1003
|
+
...
|
|
1004
|
+
|
|
1005
|
+
This is =&gt;[#wrong].
|
|
1006
|
+
|
|
1007
|
+
This is a #[test|test anchor].
|
|
1008
|
+
</code></pre></div>
|
|
1009
|
+
<p>Is translated into the following <span class="caps">HTML</span> code:</p>
|
|
1010
|
+
<div class="code"><pre><code>
|
|
1011
|
+
<p>This is a link to <a href="#test">test anchor</a>.</p>
|
|
1012
|
+
<p>...</p>
|
|
1013
|
+
<p>This is <a href="#wrong">#wrong</a>.</p>
|
|
1014
|
+
<p>This is a <a id="test">test anchor</a>.</p>
|
|
1015
|
+
</code></pre></div>
|
|
1016
|
+
<p>Additionally, the following warning message is displayed when <a href="#compile">compiling</a>:</p>
|
|
1017
|
+
<div class="code"><pre><code>
|
|
1018
|
+
warning: Bookmark 'wrong' does not exist
|
|
1019
|
+
-> source: @: aurhoting.textile
|
|
1020
|
+
-> path: document/body/bodymatter/chapter/@/textile/section/section/box/=>
|
|
1021
|
+
</code></pre></div>
|
|
1022
|
+
</div>
|
|
1023
|
+
<p>Basically, if you use the <code>=></code> and <code>#</code> macros, Glyph makes sure that:</p>
|
|
1024
|
+
<ul>
|
|
1025
|
+
<li>All links point to valid anchors within the document (regardless if the anchors are before or after the link, in snippets or included files).</li>
|
|
1026
|
+
<li>There are no duplicate anchors within the documents.</li>
|
|
1027
|
+
<li>If no title is specified as second parameter for the <code>=></code> macro, the anchor’s title is used as such.</li>
|
|
1028
|
+
</ul>
|
|
1029
|
+
<p>Besides using the <code>#</code> macro, you can also create an anchor for a header by passing an extra parameter to the <code>header</code> macro, like this: <code>header[Header Title|my_anchor]</code>.</p>
|
|
1030
|
+
<div class="note"><span class="note-title">Note</span>At present, link validation and automatic title retrieval only works with internal links (i.e. the check occurs if the first parameter of the <code>=></code> macro starts with a <code>#</code>). In the future, the macro could be extended to support external links as well. </div>
|
|
1031
|
+
</div>
|
|
1032
|
+
<div class="section">
|
|
1033
|
+
<h4 id="h_18">Evaluating Ruby code and Configuration Settings</h4>
|
|
1034
|
+
|
|
1035
|
+
<p>Glyph Language is not a full-blown programming language, as it does not provide control flow or variables, for example. <br />
|
|
1036
|
+
However, it is possible to evaluate simple ruby code snippets using the <code>ruby</code> macro (aliased to <code>%</code>), like this:</p>
|
|
1037
|
+
<ul>
|
|
1038
|
+
<li><code>%[2 + 2]</code> → 4</li>
|
|
1039
|
+
<li><code>%[Time.now]</code> → Sun Apr 04 20:30:13 +0200 2010</li>
|
|
1040
|
+
<li><code>%[Glyph::VERSION]</code> → 0.1.0</li>
|
|
1041
|
+
</ul>
|
|
1042
|
+
<p>The scope for the code evaluation is the Kernel module, (with all inclusions required by Glyph itself).</p>
|
|
1043
|
+
<p>Although it is possible to retrieve Glyph configuration settings in this way (e.g. <code>%[cfg('document.author')]</code>), the <code>config</code> macro (aliased to <code>$</code>) makes things slightly simpler (e.g. <code>$[document.author]</code>).</p>
|
|
1044
|
+
</div>
|
|
1045
|
+
<div class="section">
|
|
1046
|
+
<h4 id="img_fig">Images and Figures</h4>
|
|
1047
|
+
|
|
1048
|
+
<p>In a similar way to <a href="#links">links</a>, if you want you can include images and figures using Textile or Markdown. If you want additional features, you can use the <code>img</code> and <code>fig</code> macros, as shown in the following example:</p>
|
|
1049
|
+
<div class="box"><span class="box-title">Example</span><br />
|
|
1050
|
+
The following Glyph code:<br />
|
|
1051
|
+
<br />
|
|
1052
|
+
<div class="code"><pre><code>
|
|
1053
|
+
img[glyph.svg|20%|20%]
|
|
1054
|
+
|
|
1055
|
+
fig[example.png|An example figure.]
|
|
1056
|
+
</code></pre></div>
|
|
1057
|
+
<p>Is translated into the following <span class="caps">HTML</span> code:</p>
|
|
1058
|
+
<div class="code"><pre><code>
|
|
1059
|
+
<img src="images/glyph.svg" width="20%" height="20%" alt="-" />
|
|
1060
|
+
|
|
1061
|
+
<div class="figure">
|
|
1062
|
+
<img src="images/example.png" alt="-"/>
|
|
1063
|
+
<div class="caption">An example figure.</div>
|
|
1064
|
+
</div>
|
|
1065
|
+
</code></pre></div>
|
|
1066
|
+
</div>
|
|
1067
|
+
<div class="note"><span class="note-title">Note</span>In future releases, figures will be numbered automatically and included in a <em>List of Figures</em> section. </div>
|
|
1068
|
+
</div>
|
|
1069
|
+
</div>
|
|
1070
|
+
<div class="section">
|
|
1071
|
+
<h3 id="compile">Compiling your project</h3>
|
|
1072
|
+
|
|
1073
|
+
<p>By default, a Glyph project can be <em>compiled</em> into an <span class="caps">HTML</span> document. Additionally, Glyph can also be used to produce <span class="caps">PDF</span> documents through <a href="http://www.princexml.com/">Prince</a>, and in future releases more formats are likely to be supported.</p>
|
|
1074
|
+
<div class="section">
|
|
1075
|
+
<h4 id="stylesheets">Adding Stylesheets</h4>
|
|
1076
|
+
|
|
1077
|
+
<p>Currently, Glyph does not provide any native way to format text and pages. The reason is that there’s absolutely no need for that: <span class="caps">CSS</span> does the job just fine. In particular, <span class="caps">CSS</span> 3 offers specific attributes and elements that can be used specifically for paginated documents. That’s no replacement for LaTeX by any means, but it is enough if you’re not looking for advanced typographical features.</p>
|
|
1078
|
+
<p>You can embed <span class="caps">CSS</span> files using the <code>style</code> macro, like this:</p>
|
|
1079
|
+
<div class="code"><pre><code>
|
|
1080
|
+
style[default.css]
|
|
1081
|
+
</code></pre></div>
|
|
1082
|
+
<p>In this case, the <code>style</code> macro looks for a <code>default.css</code> file in the <code>/styles</code> folder of your Glyph project and embeds it within a <code><style></code> tag. If you supply a file with a <code>.sass</code> extension, it will interpret it as a Sass file and convert it to <span class="caps">CSS</span> automatically (if the <em>Haml</em> gem is installed).</p>
|
|
1083
|
+
</div>
|
|
1084
|
+
<div class="section">
|
|
1085
|
+
<h4 id="h_22"><span class="caps">HTML</span> output</h4>
|
|
1086
|
+
|
|
1087
|
+
<p>To compile a Glyph project to an <span class="caps">HTML</span> document, use the <code>glyph compile</code> command within your Glyph project folder. Glyph parses the <code>document.glyph</code> file (and all included files and snippets); if no errors are found, Glyph creates an <span class="caps">HTML</span> document in the <code>/output/html</code> folder. The name of the <span class="caps">HTML</span> file can be set in the configuration (<code>document.filename</code> setting).</p>
|
|
1088
|
+
<p>If you don’t want to compile the whole project, you can specify a different source, like this:</p>
|
|
1089
|
+
<div class="code"><pre><code>
|
|
1090
|
+
glyph compile -s myfile.textile
|
|
1091
|
+
</code></pre></div>
|
|
1092
|
+
</div>
|
|
1093
|
+
<div class="section">
|
|
1094
|
+
<h4 id="h_23"><span class="caps">PDF</span> Output</h4>
|
|
1095
|
+
|
|
1096
|
+
<p>To generate a <span class="caps">PDF</span> document, you must specify <code>pdf</code> as format, like this:</p>
|
|
1097
|
+
<div class="code"><pre><code>
|
|
1098
|
+
glyph compile -f pdf
|
|
1099
|
+
</code></pre></div>
|
|
1100
|
+
<p>The command above will attempt to compile the project into an <span class="caps">HTML</span> document and then call Prince to generate a <span class="caps">PDF</span> document from it. In order for this to work, you must download and install <a href="http://www.princexml.com/">Prince</a>. It’s not open source, but the free version is fully functional, and it just adds a small logo on the first page.</p>
|
|
1101
|
+
<div class="note"><span class="note-title">Note</span>Glyph v0.1.0 has been successfully tested with Prince v7.0, and the <span class="caps">PDF</span> version of this very book was generated with it. </div>
|
|
1102
|
+
</div>
|
|
1103
|
+
</div>
|
|
1104
|
+
|
|
1105
|
+
</div>
|
|
1106
|
+
<div class="chapter">
|
|
1107
|
+
|
|
1108
|
+
<h2 id="extending">Extending Glyph</h2>
|
|
1109
|
+
|
|
1110
|
+
<p>Glyph was created wih extensibility in mind. You can freely extend Glyph Language by creating or overriding macros, to do whatever you like. Macro definitions are written in pure Ruby code and placed in <code>.rb</code> files within the <code>/lib/macros</code> folder of your project.</p>
|
|
1111
|
+
<div class="section">
|
|
1112
|
+
<h3 id="h_25">Anatomy of a Macro</h3>
|
|
1113
|
+
|
|
1114
|
+
<p>This is the source code of a fairly simple macro used to format a note :</p>
|
|
1115
|
+
<div class="code"><pre><code>
|
|
1116
|
+
macro :note do
|
|
1117
|
+
%{<div class="#{@name}"><span class="note-title">#{@name.to_s.capitalize}</span>#{@value}
|
|
1118
|
+
|
|
1119
|
+
</div>}
|
|
1120
|
+
end
|
|
1121
|
+
</code></pre></div>
|
|
1122
|
+
<p>The <code>macro</code> method takes a single Symbol or String parameter, corresponding to the name of the macro. In this case, the entire block (or <em>body</em> of the macro) is a String corresponding to what we want the macro to evaluate to: a <code><div></code> tag containing a note.</p>
|
|
1123
|
+
<p>The body of the macro is evaluated in the context of the <a href="http://yardoc.org/docs/h3rald-glyph/Glyph/Macro">Glyph::Macro</a> class, therefore its instance variables (like <code>@name</code> or <code>@value</code>) can be used directly.</p>
|
|
1124
|
+
<div class="box"><span class="box-title">Why using <code>@name</code> instead of just “note”?</span><br />
|
|
1125
|
+
For the <code>note</code> macro, it absolutely makes no difference. However, by using <code>@name</code> it is possible to re-use the same code for the <code>tip</code>, <code>important</code> and <code>caution</code> macros as well, which are in fact only aliases of the <code>note</code> macro:<br />
|
|
1126
|
+
<br />
|
|
1127
|
+
<code>macro_alias :important => :note</code><br />
|
|
1128
|
+
<code>macro_alias :tip => :note</code><br />
|
|
1129
|
+
<code>macro_alias :caution => :note</code> </div>
|
|
1130
|
+
<p>The following table lists all the instance variables that can be used inside macros:</p>
|
|
1131
|
+
<table><tr><th>Variable </th>
|
|
1132
|
+
|
|
1133
|
+
<th>Description </th>
|
|
1134
|
+
</tr>
|
|
1135
|
+
|
|
1136
|
+
<tr><td><code>@node</code> </td>
|
|
1137
|
+
|
|
1138
|
+
<td>A <a href="http://yardoc.org/docs/h3rald-glyph/Node">Node</a> containing information about the macro, within the document syntax tree. Useful for accessing parent and child macros, and the current <a href="http://yardoc.org/docs/h3rald-glyph/Glyph/Document">document</a>. Normally, macro nodes contain the following keys:<br />
|
|
1139
|
+
- <code>:name</code>, the name of the macro<br />
|
|
1140
|
+
- <code>:value</code>, the value (i.e. the contents, within the delimiters) of the macro<br />
|
|
1141
|
+
- <code>:source</code>, a String identifying the source of the macro (a file, a snippet, etc.) <br />
|
|
1142
|
+
- <code>:document</code>, the parsed document tree<br />
|
|
1143
|
+
<br />
|
|
1144
|
+
Note that the first three keys can also be accessed via instance variables. </td>
|
|
1145
|
+
</tr>
|
|
1146
|
+
|
|
1147
|
+
<tr><td><code>@name</code> </td>
|
|
1148
|
+
|
|
1149
|
+
<td>The name of the macro </td>
|
|
1150
|
+
</tr>
|
|
1151
|
+
|
|
1152
|
+
<tr><td><code>@value</code> </td>
|
|
1153
|
+
|
|
1154
|
+
<td>The full contents (including parameters and nested macros) within the macro delimiters. </td>
|
|
1155
|
+
</tr>
|
|
1156
|
+
|
|
1157
|
+
<tr><td><code>@source</code> </td>
|
|
1158
|
+
|
|
1159
|
+
<td>A String identifying the source of the macro (a file, a snippet, etc.) </td>
|
|
1160
|
+
</tr>
|
|
1161
|
+
|
|
1162
|
+
<tr><td><code>@params</code> </td>
|
|
1163
|
+
|
|
1164
|
+
<td>The parameters passed to the macro. In other words, the value of the macro split by pipes (<code>|</code>). </td>
|
|
1165
|
+
</tr>
|
|
1166
|
+
</table>
|
|
1167
|
+
</div>
|
|
1168
|
+
<div class="section">
|
|
1169
|
+
<h3 id="h_26">Bookmarks and Headers</h3>
|
|
1170
|
+
|
|
1171
|
+
<p>The <a href="http://yardoc.org/docs/h3rald-glyph/Glyph/Macro">Glyph::Macro</a> class also includes a few methods to check and store bookmarks and headers. Consider for example the following source code for the <code>anchor</code> macro:</p>
|
|
1172
|
+
<div class="code"><pre><code>
|
|
1173
|
+
macro :anchor do
|
|
1174
|
+
ident, title = @params
|
|
1175
|
+
macro_error "Bookmark '#{ident}' already exists" if bookmark? ident
|
|
1176
|
+
bookmark :id => ident, :title => title
|
|
1177
|
+
%{<a id="#{ident}">#{title}</a>}
|
|
1178
|
+
end
|
|
1179
|
+
</code></pre></div> <p>The <code>bookmark?</code> method can be used to check the existance of a particular ID within the whole document, while the <code>bookmark</code> method is used to store bookmark IDs and titles. In a similar way, you can use <code>header?</code> and <code>header</code> methods to check the existance of headers within the documents or store new ones.</p>
|
|
1180
|
+
</div>
|
|
1181
|
+
<div class="section">
|
|
1182
|
+
<h3 id="h_27">Using Placeholders</h3>
|
|
1183
|
+
|
|
1184
|
+
<p>Sometimes you may need to access some data that will not be available until the entire document has been fully parsed and analyzed. For example, in order to be able to validate internal links, it is necessary to know in advance if the bookmark ID referenced in the link exists or not, either before (that’s easy) or even <em>after</em> the location of the link.</p>
|
|
1185
|
+
<p>Here’s the source code of the <code>link</code> macro:</p>
|
|
1186
|
+
<div class="code"><pre><code>
|
|
1187
|
+
macro :link do
|
|
1188
|
+
href, title = @params
|
|
1189
|
+
if href.match /^#/ then
|
|
1190
|
+
anchor = href.gsub(/^#/, '').to_sym
|
|
1191
|
+
bmk = bookmark? anchor
|
|
1192
|
+
if bmk then
|
|
1193
|
+
title ||= bmk[:title]
|
|
1194
|
+
else
|
|
1195
|
+
plac = placeholder do |document|
|
|
1196
|
+
macro_error "Bookmark '#{anchor}' does not exist" unless document.bookmarks[anchor]
|
|
1197
|
+
document.bookmarks[anchor][:title]
|
|
1198
|
+
end
|
|
1199
|
+
title ||= plac
|
|
1200
|
+
end
|
|
1201
|
+
end
|
|
1202
|
+
title ||= href
|
|
1203
|
+
%{<a href="#{href}">#{title}</a>}
|
|
1204
|
+
end
|
|
1205
|
+
</code></pre></div> <p>If there’s already a bookmark stored in the current document, then it is possible to retrieve its title and use it as link text. Otherwise, it is necessary to wait until the entire document has been fully processed and then check if the bookmark exists. To do so, use the <code>placeholder</code> method. When called, this method returns an unique placeholder, which is then substituted with the value of the block, right before the document is finalized.</p>
|
|
1206
|
+
<p>Within the <code>placeholder</code> block, the <code>document</code> parameter is, by all means, the fully analyzed document.</p>
|
|
1207
|
+
</div>
|
|
1208
|
+
<div class="section">
|
|
1209
|
+
<h3 id="h_28">Interpreting Glyph Code</h3>
|
|
1210
|
+
|
|
1211
|
+
<p>What if you need to evaluate some Glyph code <em>within</em> a macro? Say for example you want to transform a parameter in a link, and you want to make sure that link gets validated exactly like the others, in this case, you can use the <code>interpret</code> method, as follows:</p>
|
|
1212
|
+
<div class="code"><pre><code>
|
|
1213
|
+
macro :fmi do
|
|
1214
|
+
topic, href = @params
|
|
1215
|
+
link = placeholder do |document|
|
|
1216
|
+
interpret "link[#{href}]"
|
|
1217
|
+
end
|
|
1218
|
+
%{<span class="fmi">for more information on #{topic}, see #{link}</span>}
|
|
1219
|
+
end
|
|
1220
|
+
</code></pre></div> <p>When the <code>interpreter</code> method is called, the following happens:</p>
|
|
1221
|
+
<ol>
|
|
1222
|
+
<li>A new Glyph document is created from the String passed to the method.</li>
|
|
1223
|
+
<li>The bookmarks, headers and placeholders are passed from the main document to the new one. Because they are stored in Arrays or Hashes, they are passed by reference, so for example any new bookmark stored in the new document will also become available in the main document.</li>
|
|
1224
|
+
<li>Any macro included in the String is evaluated, and the resulting text is returned by the method. Note that this new document does not get finalized: in other words, placeholders will be left as they are, and they’ll eventually be replaced when <em>the main document</em> is finalized.</li>
|
|
1225
|
+
</ol>
|
|
1226
|
+
</div>
|
|
1227
|
+
<div class="section">
|
|
1228
|
+
<h3 id="h_29">Further Reading</h3>
|
|
1229
|
+
|
|
1230
|
+
<p>For more examples on how to create more complex macros, have a look at the <a href="http://github.com/h3rald/glyph/tree/master/macros/">source code</a> of the existing ones.</p>
|
|
1231
|
+
<p>To gain a deeper understanding on how macros are executed, have a look at the following Glyph classes:</p>
|
|
1232
|
+
<ul>
|
|
1233
|
+
<li><a href="http://yardoc.org/docs/h3rald-glyph/Glyph/Macro">Glyph::Macro</a></li>
|
|
1234
|
+
<li><a href="http://yardoc.org/docs/h3rald-glyph/Glyph/Interpreter">Glyph::Interpreter</a></li>
|
|
1235
|
+
<li><a href="http://yardoc.org/docs/h3rald-glyph/Glyph/Document">Glyph::Document</a></li>
|
|
1236
|
+
<li><a href="http://yardoc.org/docs/h3rald-glyph/Glyph/Node">Node</a></li>
|
|
1237
|
+
</ul>
|
|
1238
|
+
</div>
|
|
1239
|
+
|
|
1240
|
+
</div>
|
|
1241
|
+
<div class="chapter">
|
|
1242
|
+
|
|
1243
|
+
<h2 id="h_30">Troubleshooting</h2>
|
|
1244
|
+
|
|
1245
|
+
<p>This chapter lists the most common error messages that can be returned when running a Glyph command. It does not aim to be an exhaustive list, especially if you <a href="#extending">extended</a> Glyph by creating your own macros.</p>
|
|
1246
|
+
<div class="section">
|
|
1247
|
+
<h3 id="h_31">Generic Errors</h3>
|
|
1248
|
+
|
|
1249
|
+
<table style="width:100%;">
|
|
1250
|
+
<tr>
|
|
1251
|
+
<th style="width:30%">Error Message</th>
|
|
1252
|
+
<th>Description</th>
|
|
1253
|
+
</tr>
|
|
1254
|
+
<tr>
|
|
1255
|
+
<td>Document contains syntax errors</td>
|
|
1256
|
+
<td>This error is returned if the document was not parsed because of one or more syntax error. <br />
|
|
1257
|
+
<br />
|
|
1258
|
+
<strong>At present, no indication on the exact location of the error(s) is provided</strong>, so the only way to determine what went wrong is to try compiling a single file at a time (<code>glyph compile -s source-file</code>), and examine more closely the source of the files that do not compile.</td>
|
|
1259
|
+
</tr>
|
|
1260
|
+
|
|
1261
|
+
<tr>
|
|
1262
|
+
<td>Invalid alias: macro ‘<em>macro-name</em>’ already exists</td>
|
|
1263
|
+
<td>The alias name supplied to the <code>macro_alias</code> method has already been used for another macro or alias.</td>
|
|
1264
|
+
</tr>
|
|
1265
|
+
|
|
1266
|
+
<tr>
|
|
1267
|
+
<td>Undefined macro ‘<em>macro-name</em>’</td>
|
|
1268
|
+
<td>The document contains a macro that does not exist, i.e. it is not a standard or used-defined <a href="#macro_ref">Glyph macro or alias</a>.</td>
|
|
1269
|
+
</tr>
|
|
1270
|
+
|
|
1271
|
+
<tr>
|
|
1272
|
+
<td>An error occurred when generating <em>file-name</em>.pdf</td>
|
|
1273
|
+
<td>Returned if Prince could not generate the <span class="caps">PDF</span> file or if Prince is not installed. Normally, Prince provides additional details on the specific error(s).</td>
|
|
1274
|
+
</tr>
|
|
1275
|
+
|
|
1276
|
+
<tr>
|
|
1277
|
+
<td>Glyph cannot generate <span class="caps">PDF</span>. Please specify a valid pdf_renderer setting</td>
|
|
1278
|
+
<td>Returned if the <code>pdf_renderer</code> setting has not be set to a valid <span class="caps">PDF</span> renderer. Currently, the only supported value for this setting is <code>prince</code>.</td>
|
|
1279
|
+
</tr>
|
|
1280
|
+
|
|
1281
|
+
<tr>
|
|
1282
|
+
<td>The current directory is not a valid Glyph project</td>
|
|
1283
|
+
<td>Returned if a glyph command was executed outside a valid glyph project directory.</td>
|
|
1284
|
+
</tr>
|
|
1285
|
+
|
|
1286
|
+
<tr>
|
|
1287
|
+
<td>Invalid snippet file</td>
|
|
1288
|
+
<td>The <code>snippet.yml</code> file contains invalid data. Most likely, it does not evaluate to a Ruby Hash.</td>
|
|
1289
|
+
</tr>
|
|
1290
|
+
|
|
1291
|
+
<tr>
|
|
1292
|
+
<td>Directory ‘<em>directory-name</em>’ is not empty</td>
|
|
1293
|
+
<td>Returned when executing <code>glyph init</code> in a directory that is not empty.</td>
|
|
1294
|
+
</tr>
|
|
1295
|
+
|
|
1296
|
+
<tr>
|
|
1297
|
+
<td>File ‘<em>file-name</em>’ already exists</td>
|
|
1298
|
+
<td>Returned if the name of an existing file was specified as a parameter for the <code>glyph add</code> command.</td>
|
|
1299
|
+
</tr>
|
|
1300
|
+
</table>
|
|
1301
|
+
</div>
|
|
1302
|
+
<div class="section">
|
|
1303
|
+
<h3 id="h_32">Command Errors</h3>
|
|
1304
|
+
|
|
1305
|
+
<table style="width:100%;">
|
|
1306
|
+
<tr>
|
|
1307
|
+
<th style="width:30%">Error Message</th>
|
|
1308
|
+
<th>Description</th>
|
|
1309
|
+
</tr>
|
|
1310
|
+
<tr>
|
|
1311
|
+
<td>Please specify a file name</td>
|
|
1312
|
+
<td>No file name was specified for the <code>glyph add</code> command.</td>
|
|
1313
|
+
</tr>
|
|
1314
|
+
|
|
1315
|
+
<tr>
|
|
1316
|
+
<td>Output target not specified</td>
|
|
1317
|
+
<td>Returned if no target was specified for the <code>glyph compile</code> command <em>and</em> if the <code>document.output</code> configuration setting is not set.</td>
|
|
1318
|
+
</tr>
|
|
1319
|
+
|
|
1320
|
+
<tr>
|
|
1321
|
+
<td>Unknown output target ‘<em>target-name</em>’</td>
|
|
1322
|
+
<td>An unsupported output target was specified for the <code>glyph compile</code> command. Only the following output targets are supported:<br />
|
|
1323
|
+
- <code>html</code><br />
|
|
1324
|
+
- <code>pdf</code></td>
|
|
1325
|
+
</tr>
|
|
1326
|
+
|
|
1327
|
+
<tr>
|
|
1328
|
+
<td>Too few/too many arguments</td>
|
|
1329
|
+
<td>Returned if the <code>glyph config</code> command was used with no arguments or more than two arguments respectively.</td>
|
|
1330
|
+
</tr>
|
|
1331
|
+
|
|
1332
|
+
<tr>
|
|
1333
|
+
<td>Unknown setting ‘<em>setting-name</em>’</td>
|
|
1334
|
+
<td>The name of an unknown setting was specified for the <code>glyph config</code> command.</td>
|
|
1335
|
+
</tr>
|
|
1336
|
+
</table>
|
|
1337
|
+
</div>
|
|
1338
|
+
<div class="section">
|
|
1339
|
+
<h3 id="h_33">Macro Errors</h3>
|
|
1340
|
+
|
|
1341
|
+
<p>The following errors are displayed in the form:</p>
|
|
1342
|
+
<p><em>macro-path</em> <em>message</em></p>
|
|
1343
|
+
<p>Where:</p>
|
|
1344
|
+
<ul>
|
|
1345
|
+
<li><em>macro-path</em> is the full path to the macro that returned the error, within the document syntax tree, e.g. <code>document/body/bodymatter/chapter/section/header/&</code> if the error occurrent in a snippet within the header of a section in the <code>bodymatter</code> part of the document.</li>
|
|
1346
|
+
<li><em>message</em> is the error message.</li>
|
|
1347
|
+
</ul>
|
|
1348
|
+
<table style="width:100%;">
|
|
1349
|
+
<tr>
|
|
1350
|
+
<th style="width:30%">Error Message</th>
|
|
1351
|
+
<th>Description</th>
|
|
1352
|
+
</tr>
|
|
1353
|
+
<tr>
|
|
1354
|
+
<td>Mutual inclusion</td>
|
|
1355
|
+
<td>This error is returned if a catch-22 situation occurs with macro inclusion, for example if the body of a snippet includes a reference to the same snippet.</td>
|
|
1356
|
+
</tr>
|
|
1357
|
+
|
|
1358
|
+
<tr>
|
|
1359
|
+
<td>Snippet ‘<em>snippet-id</em>’ does not exist</td>
|
|
1360
|
+
<td>Returned by the <a href="#m_snippet">snippet</a> macro if an invalid snippet was supplied.</td>
|
|
1361
|
+
</tr>
|
|
1362
|
+
|
|
1363
|
+
<tr>
|
|
1364
|
+
<td>File ‘<em>file-name</em>’ not found</td>
|
|
1365
|
+
<td>Returned by the <a href="#m_include">include</a> macro if an invalid file was supplied.</td>
|
|
1366
|
+
</tr>
|
|
1367
|
+
|
|
1368
|
+
<tr>
|
|
1369
|
+
<td>Filter macro ‘<em>macro-name</em>’ not found</td>
|
|
1370
|
+
<td>Returned by the <a href="#m_include">include</a> macro macro if the <code>filters.by_file_extension</code> setting is set to <code>true</code> but the file extension of the included file is not recognized as a filter macro.</td>
|
|
1371
|
+
</tr>
|
|
1372
|
+
|
|
1373
|
+
<tr>
|
|
1374
|
+
<td>RedCloth gem not installed. Please run: gem insall RedCloth</td>
|
|
1375
|
+
<td>Returned by the <a href="#m_textile">textile</a> macro if the RedCloth gem is not installed.</td>
|
|
1376
|
+
</tr>
|
|
1377
|
+
|
|
1378
|
+
<tr>
|
|
1379
|
+
<td>No MarkDown converter installed. Please run: gem insall bluecloth</td>
|
|
1380
|
+
<td>Returned by the <a href="#m_markdown">markdown</a> macro if no valid Markup converter gem is installed. <br />
|
|
1381
|
+
<br />
|
|
1382
|
+
Glyph checks for: BlueCloth, Maruku, Kramdown and RDiscount.</td>
|
|
1383
|
+
</tr>
|
|
1384
|
+
|
|
1385
|
+
<tr>
|
|
1386
|
+
<td>Image/Figure not found</td>
|
|
1387
|
+
<td>Retured by the <a href="#m_img">img</a> macro or the <a href="#m_fig">fig</a> macro respectively, if the specified image file could not be found within the <code>images/</code> folder.</td>
|
|
1388
|
+
</tr>
|
|
1389
|
+
|
|
1390
|
+
<tr>
|
|
1391
|
+
<td>Bookmark ‘<em>bookmark-name</em>’ already exists</td>
|
|
1392
|
+
<td>Returned by the <a href="#m_anchor">anchor</a> macro or by the <a href="#m_header">header</a> macro if the anchor ID supplied as parameter has already been used in the document.</td>
|
|
1393
|
+
</tr>
|
|
1394
|
+
|
|
1395
|
+
<tr>
|
|
1396
|
+
<td>Bookmark ‘<em>bookmark-name</em>’ already exists</td>
|
|
1397
|
+
<td>Returned by the <a href="#m_link">link</a> macro if the anchor ID supplied as parameter has not been used in the document.</td>
|
|
1398
|
+
</tr>
|
|
1399
|
+
|
|
1400
|
+
<tr>
|
|
1401
|
+
<td>Stylesheet ‘<em>file-name</em>’ not found</td>
|
|
1402
|
+
<td>Returned by the <a href="#m_style">style</a> macro if the .css or .sass file supplied as parameter was not found in the <code>styles/</code> directory.</td>
|
|
1403
|
+
</tr>
|
|
1404
|
+
|
|
1405
|
+
<tr>
|
|
1406
|
+
<td>Haml is not installed. Please run: gem install haml</td>
|
|
1407
|
+
<td>Returned by the <a href="#m_style">style</a> macro macro if a .sass file was passed as parameter but the Haml gem is not installed.</td>
|
|
1408
|
+
</tr>
|
|
1409
|
+
</table>
|
|
1410
|
+
</div>
|
|
1411
|
+
|
|
1412
|
+
</div>
|
|
1413
|
+
|
|
1414
|
+
</div>
|
|
1415
|
+
<div class="backmatter">
|
|
1416
|
+
|
|
1417
|
+
<div class="appendix">
|
|
1418
|
+
|
|
1419
|
+
<h2 id="cmd_ref">Command Reference</h2>
|
|
1420
|
+
|
|
1421
|
+
<p>Glyph’s command-line interface has been built using the <a href="http://github.com/davetron5000/gli">gli</a> (Git-like interface) gem. Therefore, Glyph commands are all written like this:</p>
|
|
1422
|
+
<p><code>glyph</code> <em>global-options</em> command <em>options</em> <em>parameters</em></p>
|
|
1423
|
+
<p>Where:</p>
|
|
1424
|
+
<ul>
|
|
1425
|
+
<li><em>global-options</em> and <em>options</em> are in the form: <code>-n</code> <em>value</em> or <code>--name=</code><em>value</em>, e.g. <code>-f pdf</code> or <code>--format=pdf</code></li>
|
|
1426
|
+
<li><em>parameters</em> are separated by whitespaces, and can be wrapped in quotes.</li>
|
|
1427
|
+
</ul>
|
|
1428
|
+
<div class="section">
|
|
1429
|
+
<h3 id="h_35">Global Options</h3>
|
|
1430
|
+
|
|
1431
|
+
<div class="section">
|
|
1432
|
+
<h4 id="h_36"><code>-d</code>, <code>--debug</code></h4>
|
|
1433
|
+
<p>If specified, the command is executed in debug mode and additional diagnostic information is printed on the screen.</p>
|
|
1434
|
+
</div>
|
|
1435
|
+
</div>
|
|
1436
|
+
<div class="section">
|
|
1437
|
+
<h3 id="h_37"><code>add</code></h3>
|
|
1438
|
+
<p>Creates a new text file in the <code>text/</code> folder.</p>
|
|
1439
|
+
<p><strong>Example:</strong> <code>glyph add introduction.textile</code></p>
|
|
1440
|
+
<div class="section">
|
|
1441
|
+
<h4 id="h_38">Parameters</h4>
|
|
1442
|
+
|
|
1443
|
+
<table style="width:100%;">
|
|
1444
|
+
<tr>
|
|
1445
|
+
<th style="width:30%">Parameter</th>
|
|
1446
|
+
<th>Description</th>
|
|
1447
|
+
</tr>
|
|
1448
|
+
<tr>
|
|
1449
|
+
<td>file-name</td>
|
|
1450
|
+
<td>The name (or relative path) of the new file to be created.</td>
|
|
1451
|
+
</tr>
|
|
1452
|
+
</table>
|
|
1453
|
+
</div>
|
|
1454
|
+
</div>
|
|
1455
|
+
<div class="section">
|
|
1456
|
+
<h3 id="h_39"><code>compile</code></h3>
|
|
1457
|
+
<p>Compiles a Glyph document into an output file. If no options are specified, the <code>document.glyph</code> file is used as source to produce a standalone <span class="caps">HTML</span> file.</p>
|
|
1458
|
+
<p><strong>Example:</strong> <code>glyph compile -f pdf</code></p>
|
|
1459
|
+
<div class="section">
|
|
1460
|
+
<h4 id="h_40">Options</h4>
|
|
1461
|
+
|
|
1462
|
+
<table style="width:100%;">
|
|
1463
|
+
<tr>
|
|
1464
|
+
<th style="width:30%">Option</th>
|
|
1465
|
+
<th>Description</th>
|
|
1466
|
+
</tr>
|
|
1467
|
+
<tr>
|
|
1468
|
+
<td>-s (--source)</td>
|
|
1469
|
+
<td>
|
|
1470
|
+
<p>The source file to compile. <br />
|
|
1471
|
+
<strong>Default:</strong> <code>document.glyph</code></p>
|
|
1472
|
+
</td>
|
|
1473
|
+
</tr>
|
|
1474
|
+
|
|
1475
|
+
<tr>
|
|
1476
|
+
<td>-f (--format)</td>
|
|
1477
|
+
<td>
|
|
1478
|
+
<p>The format of the output file.<br />
|
|
1479
|
+
<strong>Default:</strong> <code>html</code><br />
|
|
1480
|
+
<strong>Possible Values:</strong> <code>html, pdf</code></p>
|
|
1481
|
+
</td>
|
|
1482
|
+
</tr>
|
|
1483
|
+
</table>
|
|
1484
|
+
</div>
|
|
1485
|
+
</div>
|
|
1486
|
+
<div class="section">
|
|
1487
|
+
<h3 id="h_41"><code>config</code></h3>
|
|
1488
|
+
<p>Gets or sets a configuration setting in the project or global configuration file (<span class="fmi">for more information on configuration files, see <a href="#cfg">Project Configuration</a></span>).</p>
|
|
1489
|
+
<p><strong>Examples:</strong> <br />
|
|
1490
|
+
<code>glyph config document.filename</code><br />
|
|
1491
|
+
<code>glyph config -g document.author "Fabio Cevasco"</code></p>
|
|
1492
|
+
|
|
1493
|
+
<div class="section">
|
|
1494
|
+
<h4 id="h_42">Options</h4>
|
|
1495
|
+
|
|
1496
|
+
<table style="width:100%;">
|
|
1497
|
+
<tr>
|
|
1498
|
+
<th style="width:30%">Option</th>
|
|
1499
|
+
<th>Description</th>
|
|
1500
|
+
</tr>
|
|
1501
|
+
<tr>
|
|
1502
|
+
<td>-g (--global)</td>
|
|
1503
|
+
<td>
|
|
1504
|
+
<p>If specified, the global configuration file is processed instead of the project file.<br />
|
|
1505
|
+
<strong>Default:</strong> <code>false</code></p>
|
|
1506
|
+
</td>
|
|
1507
|
+
</tr>
|
|
1508
|
+
</table>
|
|
1509
|
+
</div>
|
|
1510
|
+
|
|
1511
|
+
<div class="section">
|
|
1512
|
+
<h4 id="h_43">Parameters</h4>
|
|
1513
|
+
|
|
1514
|
+
<table style="width:100%;">
|
|
1515
|
+
<tr>
|
|
1516
|
+
<th style="width:30%">Parameter</th>
|
|
1517
|
+
<th>Description</th>
|
|
1518
|
+
</tr>
|
|
1519
|
+
<tr>
|
|
1520
|
+
<td>setting</td>
|
|
1521
|
+
<td>The name of a valid <a href="#cfg_ref">configuration setting</a>.</td>
|
|
1522
|
+
</tr>
|
|
1523
|
+
|
|
1524
|
+
<tr>
|
|
1525
|
+
<td>value</td>
|
|
1526
|
+
<td>The new value of the configuration setting.</td>
|
|
1527
|
+
</tr>
|
|
1528
|
+
</table>
|
|
1529
|
+
</div>
|
|
1530
|
+
</div>
|
|
1531
|
+
<div class="section">
|
|
1532
|
+
<h3 id="h_44"><code>init</code></h3>
|
|
1533
|
+
<p>Creates a new Glyph project in the current directory (if empty).</p>
|
|
1534
|
+
<p><strong>Example:</strong> <code>glyph init</code></p>
|
|
1535
|
+
</div>
|
|
1536
|
+
<div class="section">
|
|
1537
|
+
<h3 id="c_todo"><code>todo</code></h3>
|
|
1538
|
+
<p>Prints all the todo items saved using the <a href="#m_todo">todo</a> macro.</p>
|
|
1539
|
+
<p><strong>Example:</strong> <code>glyph todo</code></p>
|
|
1540
|
+
</div>
|
|
1541
|
+
|
|
1542
|
+
</div>
|
|
1543
|
+
<div class="appendix">
|
|
1544
|
+
|
|
1545
|
+
<h2 id="macro_ref">Macro Reference</h2>
|
|
1546
|
+
|
|
1547
|
+
<div class="section">
|
|
1548
|
+
<h3 id="h_47">Common Macros</h3>
|
|
1549
|
+
|
|
1550
|
+
<div class="section">
|
|
1551
|
+
<h4 id="m_comment"><code>comment</code></h4>
|
|
1552
|
+
<p>Evaluates to nothing. Used to add comments in a Glyph document that will not be displayed in output files.</p>
|
|
1553
|
+
<p><strong>Aliases:</strong> <code>--</code><br />
|
|
1554
|
+
<strong>Example:</strong> <code>--[This is a comment. It will not be displayed in the output]</code></p>
|
|
1555
|
+
</div>
|
|
1556
|
+
|
|
1557
|
+
<div class="section">
|
|
1558
|
+
<h4 id="m_todo"><code>todo</code></h4>
|
|
1559
|
+
<p>Saves the value as a <span class="caps">TODO</span> item, which can be printed using the <a href="#c_todo">todo</a> command.</p>
|
|
1560
|
+
<p><strong>Example:</strong> <code>todo[Remember to do this.]</code></p>
|
|
1561
|
+
</div>
|
|
1562
|
+
|
|
1563
|
+
<div class="section">
|
|
1564
|
+
<h4 id="m_snippet"><code>snippet</code></h4>
|
|
1565
|
+
<p>Evaluates to the snippet referenced by its value.</p>
|
|
1566
|
+
<p><strong>Aliases:</strong> <code>&</code><br />
|
|
1567
|
+
<strong>Example:</strong> <code>&[glang]</code></p>
|
|
1568
|
+
</div>
|
|
1569
|
+
|
|
1570
|
+
<div class="section">
|
|
1571
|
+
<h4 id="m_include"><code>include</code></h4>
|
|
1572
|
+
<p>Evaluates to the contents of a text file stored in the <code>text/</code> directory referenced by its value. If the <a href="#s_filters_by_file_extension">filters.by_file_extension</a> setting is <code>true</code>, filters the contents of the file using the <a href="#f_macros">filter macro</a> corresponding to the file extension.</p>
|
|
1573
|
+
<p><strong>Aliases:</strong> <code>@</code><br />
|
|
1574
|
+
<strong>Example:</strong> <code>@[introduction.textile]</code></p>
|
|
1575
|
+
</div>
|
|
1576
|
+
|
|
1577
|
+
<div class="section">
|
|
1578
|
+
<h4 id="m_ruby"><code>ruby</code></h4>
|
|
1579
|
+
<p>Evaluates its value as Ruby code (using <code>Kernel#instance_eval</code>).</p>
|
|
1580
|
+
<p><strong>Aliases:</strong> <code>%</code></p>
|
|
1581
|
+
<p><strong>Examples:</strong> <br />
|
|
1582
|
+
<code>%[Time.now]</code><br />
|
|
1583
|
+
<code>%[Glyph::VERSION]</code></p>
|
|
1584
|
+
</div>
|
|
1585
|
+
|
|
1586
|
+
<div class="section">
|
|
1587
|
+
<h4 id="m_config"><code>config</code></h4>
|
|
1588
|
+
<p>Evaluates to the configuration setting referenced by its value.</p>
|
|
1589
|
+
<p><strong>Aliases:</strong> <code>$</code><br />
|
|
1590
|
+
<strong>Example:</strong> <code>$[document.author]</code></p>
|
|
1591
|
+
</div>
|
|
1592
|
+
|
|
1593
|
+
<div class="section">
|
|
1594
|
+
<h4 id="m_escape"><code>escape</code></h4>
|
|
1595
|
+
<p>Evaluates to its value. Commonly used with the escaping delimiters <code>[=</code> and <code>=]</code>.</p>
|
|
1596
|
+
<p><strong>Aliases:</strong> <code>.</code><br />
|
|
1597
|
+
<strong>Example:</strong> <code>.[=Macros are escaped here =>[#test].=]</code></p>
|
|
1598
|
+
</div>
|
|
1599
|
+
</div>
|
|
1600
|
+
<div class="section">
|
|
1601
|
+
<h3 id="f_macros">Filter Macros</h3>
|
|
1602
|
+
|
|
1603
|
+
<div class="section">
|
|
1604
|
+
<h4 id="m_textile"><code>textile</code></h4>
|
|
1605
|
+
<p>Uses the RedCloth gem to transform the value into <span class="caps">HTML</span> or LaTeX, depending on the value of the <a href="#s_filters_target">filters.target</a> setting.</p>
|
|
1606
|
+
<p>If the <a href="#s_filters_by_file_extension">filters.by_file_extension</a> setting is <code>true</code>, this macro is called automatically on <a href="#m_include">included</a> files with a <code>.textile</code> extension.</p>
|
|
1607
|
+
<p><strong>Example:</strong> <code>textile[This is a *strong emphasis*.]</code></p>
|
|
1608
|
+
</div>
|
|
1609
|
+
|
|
1610
|
+
<div class="section">
|
|
1611
|
+
<h4 id="m_markdown"><code>markdown</code></h4>
|
|
1612
|
+
<p>Uses a markdown converter (BlueCloth, RDiscount, Maruku or Kramdown) to transform the value into <span class="caps">HTML</span> if the <a href="#s_filters_target">filters.target</a> setting is set to <code>html</code>.</p>
|
|
1613
|
+
<p>If the <a href="#s_filters_by_file_extension">filters.by_file_extension</a> setting is <code>true</code>, this macro is called automatically on <a href="#m_include">included</a> files with a <code>.markdown</code> or a <code>.md</code> extension.</p>
|
|
1614
|
+
<p><strong>Example:</strong> <code>markdown[This is *emphasized* text.]</code></p>
|
|
1615
|
+
</div>
|
|
1616
|
+
</div>
|
|
1617
|
+
<div class="section">
|
|
1618
|
+
<h3 id="h_58">Block Macros</h3>
|
|
1619
|
+
|
|
1620
|
+
<div class="section">
|
|
1621
|
+
<h4 id="m_note"><code>note</code></h4>
|
|
1622
|
+
<p>Creates a note <code>div</code> containing the value.</p>
|
|
1623
|
+
<p><strong>Aliases:</strong> <code>important, caution, tip</code><br />
|
|
1624
|
+
<strong>Example:</strong> <code>note[This is a note.]</code></p>
|
|
1625
|
+
</div>
|
|
1626
|
+
|
|
1627
|
+
<div class="section">
|
|
1628
|
+
<h4 id="m_box"><code>box</code></h4>
|
|
1629
|
+
<p>Creates a titled box <code>div</code>.</p>
|
|
1630
|
+
<p><strong>Example:</strong></p>
|
|
1631
|
+
<div class="code"><pre><code>
|
|
1632
|
+
box[Why boxes?|
|
|
1633
|
+
Boxes can be used to make a section of text stand out from the rest of the document.
|
|
1634
|
+
]
|
|
1635
|
+
</code></pre></div>
|
|
1636
|
+
</div>
|
|
1637
|
+
|
|
1638
|
+
<div class="section">
|
|
1639
|
+
<h4 id="m_code"><code>code</code></h4>
|
|
1640
|
+
<p>Used to render a block of code within <code>pre</code> and <code>code</code> tags. For inline code, see the <a href="#m_codeph">codeph</a> macro.</p>
|
|
1641
|
+
<p><strong>Example:</strong></p>
|
|
1642
|
+
<div class="code"><pre><code>
|
|
1643
|
+
code[
|
|
1644
|
+
def hello
|
|
1645
|
+
puts "Hello World"
|
|
1646
|
+
end
|
|
1647
|
+
]
|
|
1648
|
+
</code></pre></div>
|
|
1649
|
+
</div>
|
|
1650
|
+
|
|
1651
|
+
<div class="section">
|
|
1652
|
+
<h4 id="m_title"><code>title</code></h4>
|
|
1653
|
+
<p>Renders the title of the document (based on the <a href="#s_document_title">document.title</a> setting) within a <code>h1</code> tag.</p>
|
|
1654
|
+
<p><strong>Example:</strong> <code>title[]</code></p>
|
|
1655
|
+
</div>
|
|
1656
|
+
|
|
1657
|
+
<div class="section">
|
|
1658
|
+
<h4 id="m_subtitle"><code>subtitle</code></h4>
|
|
1659
|
+
<p>Renders the subtitle of the document (based on the <a href="#s_document_subtitle">document.subtitle</a> setting) within a <code>h2</code> tag.</p>
|
|
1660
|
+
<p><strong>Example:</strong> <code>subtitle[]</code></p>
|
|
1661
|
+
</div>
|
|
1662
|
+
|
|
1663
|
+
<div class="section">
|
|
1664
|
+
<h4 id="m_pubdate"><code>pubdate</code></h4>
|
|
1665
|
+
<p>Evaluates to a date string (in the format: <em>current-month</em> <em>current-year</em>; or <em>%B</em> <em>%Y</em>), within a <code>div</code> tag.</p>
|
|
1666
|
+
<p><strong>Example:</strong> <code>pubdate[]</code></p>
|
|
1667
|
+
</div>
|
|
1668
|
+
|
|
1669
|
+
<div class="section">
|
|
1670
|
+
<h4 id="m_img"><code>img</code></h4>
|
|
1671
|
+
<p>Includes an image in the document, optionally scaled according to the specified width and height. The image must be stored within the <code>images/</code> directory of the current project.</p>
|
|
1672
|
+
<p><strong>Examples:</strong> <br />
|
|
1673
|
+
<code>img[icon.png]</code><br />
|
|
1674
|
+
<code>img[holidays/landscape.jpg|70%]</code><br />
|
|
1675
|
+
<code>img[logo.svg|50%|50%]</code></p>
|
|
1676
|
+
</div>
|
|
1677
|
+
|
|
1678
|
+
<div class="section">
|
|
1679
|
+
<h4 id="m_fig"><code>fig</code></h4>
|
|
1680
|
+
<p>Includes an image in the document, with an optional caption.</p>
|
|
1681
|
+
<p><strong>Examples:</strong> <br />
|
|
1682
|
+
<code>fig[diagram.png]</code><br />
|
|
1683
|
+
<code>fig[graph.png|Monthly pageviews]</code></p>
|
|
1684
|
+
</div>
|
|
1685
|
+
|
|
1686
|
+
<div class="section">
|
|
1687
|
+
<h4 id="m_table"><code>table</code></h4>
|
|
1688
|
+
<p>Evaluates to an <span class="caps">HTML</span> table. Used in conjunction with the <a href="#m_tr"><code>tr</code></a>, <a href="#m_td"><code>td</code></a> and <a href="#m_th"><code>th</code></a> macros.</p>
|
|
1689
|
+
<p><strong>Example:</strong></p>
|
|
1690
|
+
<div class="code"><pre><code>
|
|
1691
|
+
table[
|
|
1692
|
+
tr[
|
|
1693
|
+
th[Name]
|
|
1694
|
+
th[Value]
|
|
1695
|
+
]
|
|
1696
|
+
tr[
|
|
1697
|
+
td[A]
|
|
1698
|
+
td[1]
|
|
1699
|
+
]
|
|
1700
|
+
tr[
|
|
1701
|
+
td[B]
|
|
1702
|
+
td[2]
|
|
1703
|
+
]
|
|
1704
|
+
]
|
|
1705
|
+
</code></pre></div>
|
|
1706
|
+
</div>
|
|
1707
|
+
|
|
1708
|
+
<div class="section">
|
|
1709
|
+
<h4 id="m_tr"><code>tr</code></h4>
|
|
1710
|
+
<p>See <a href="#m_table"><code>table</code></a>.</p>
|
|
1711
|
+
</div>
|
|
1712
|
+
|
|
1713
|
+
<div class="section">
|
|
1714
|
+
<h4 id="m_th"><code>th</code></h4>
|
|
1715
|
+
<p>See <a href="#m_table"><code>table</code></a>.</p>
|
|
1716
|
+
</div>
|
|
1717
|
+
|
|
1718
|
+
<div class="section">
|
|
1719
|
+
<h4 id="m_td"><code>td</code></h4>
|
|
1720
|
+
<p>See <a href="#m_table"><code>table</code></a>.</p>
|
|
1721
|
+
</div>
|
|
1722
|
+
</div>
|
|
1723
|
+
<div class="section">
|
|
1724
|
+
<h3 id="h_71">Inline Macros</h3>
|
|
1725
|
+
|
|
1726
|
+
<div class="section">
|
|
1727
|
+
<h4 id="m_anchor"><code>anchor</code></h4>
|
|
1728
|
+
<p>Creates a named anchor (or bookmark).</p>
|
|
1729
|
+
<p><strong>Aliases:</strong> <code>bookmark, #</code><br />
|
|
1730
|
+
<strong>Example:</strong> <code>#[test|Test Bookmark]</code></p>
|
|
1731
|
+
</div>
|
|
1732
|
+
|
|
1733
|
+
<div class="section">
|
|
1734
|
+
<h4 id="m_link"><code>link</code></h4>
|
|
1735
|
+
<p>Creates an hyperlink (<span class="fmi">for more information on creating links, see <a href="#links">Links and Bookmarks</a></span>).</p>
|
|
1736
|
+
<p><strong>Aliases:</strong> <code>=></code></p>
|
|
1737
|
+
<p><strong>Examples:</strong> <br />
|
|
1738
|
+
<code>=>[#introduction]</code><br />
|
|
1739
|
+
<code>=>[#troub|Troubleshooting]</code><br />
|
|
1740
|
+
<code>=>[http://www.h3rald.com|H3RALD.com]</code></p>
|
|
1741
|
+
</div>
|
|
1742
|
+
|
|
1743
|
+
<div class="section">
|
|
1744
|
+
<h4 id="m_codeph"><code>codeph</code></h4>
|
|
1745
|
+
<p>Wraps the value in a <code>code</code> tag.</p>
|
|
1746
|
+
<p><strong>Example:</strong> <code>codeph[Kernel.instance_eval]</code></p>
|
|
1747
|
+
</div>
|
|
1748
|
+
|
|
1749
|
+
<div class="section">
|
|
1750
|
+
<h4 id="m_fmi"><code>fmi</code></h4>
|
|
1751
|
+
<p>Creates a <em>For More Information</em> link (for an example usage, see the <a href="#m_link">link</a> macro).</p>
|
|
1752
|
+
<p><strong>Example:</strong> <code>fmi[creating links|#links]</code></p>
|
|
1753
|
+
</div>
|
|
1754
|
+
</div>
|
|
1755
|
+
<div class="section">
|
|
1756
|
+
<h3 id="h_76">Structure Macros</h3>
|
|
1757
|
+
|
|
1758
|
+
<div class="section">
|
|
1759
|
+
<h4 id="m_div"><code>div</code></h4>
|
|
1760
|
+
<p>Creates a <code>div</code> tag.</p>
|
|
1761
|
+
<p><strong>Aliases:</strong></p>
|
|
1762
|
+
</div>
|
|
1763
|
+
|
|
1764
|
+
<div class="section">
|
|
1765
|
+
<h4 id="m_header"><code>header</code></h4>
|
|
1766
|
+
<p>Creates an <code>h2</code>, <code>h3</code>, <code>h4</code>, etc. header (<span class="fmi">for more information on using headers, see <a href="#sec_head">Sections and Headers</a></span>).</p>
|
|
1767
|
+
<p><strong>Examples:</strong> <br />
|
|
1768
|
+
<code>header[Introduction]</code><br />
|
|
1769
|
+
<code>header[Getting Started|gs]</code></p>
|
|
1770
|
+
</div>
|
|
1771
|
+
|
|
1772
|
+
<div class="section">
|
|
1773
|
+
<h4 id="m_document"><code>document</code></h4>
|
|
1774
|
+
<p>The root macro used in every Glyph document.</p>
|
|
1775
|
+
</div>
|
|
1776
|
+
|
|
1777
|
+
<div class="section">
|
|
1778
|
+
<h4 id="m_body"><code>body</code></h4>
|
|
1779
|
+
<p>Creates a <code>body</code> tag.</p>
|
|
1780
|
+
</div>
|
|
1781
|
+
|
|
1782
|
+
<div class="section">
|
|
1783
|
+
<h4 id="m_head"><code>head</code></h4>
|
|
1784
|
+
<p>Creates a <code>head</code> tag, pre-populated with <code>title</code> and author/copyright meta tags.</p>
|
|
1785
|
+
</div>
|
|
1786
|
+
|
|
1787
|
+
<div class="section">
|
|
1788
|
+
<h4 id="m_style"><code>style</code></h4>
|
|
1789
|
+
<p>Embeds the content of a <span class="caps">CSS</span> or Sass file within a <code>style</code> tag (<span class="fmi">for more information on stylesheets, see <a href="#stylesheets">Adding Stylesheets</a></span>).</p>
|
|
1790
|
+
<p><strong>Example:</strong> <code>style[default.css]</code></p>
|
|
1791
|
+
</div>
|
|
1792
|
+
|
|
1793
|
+
<div class="section">
|
|
1794
|
+
<h4 id="m_toc"><code>toc</code></h4>
|
|
1795
|
+
<p>Generates a <em>Table of Contents</em> based on how sections and headers are nested in the current document.</p>
|
|
1796
|
+
<p><strong>Example:</strong> <code>toc[]</code></p>
|
|
1797
|
+
</div>
|
|
1798
|
+
</div>
|
|
1799
|
+
|
|
1800
|
+
</div>
|
|
1801
|
+
<div class="appendix">
|
|
1802
|
+
|
|
1803
|
+
<h2 id="cfg_ref">Configuration Reference</h2>
|
|
1804
|
+
|
|
1805
|
+
</div>
|
|
1806
|
+
|
|
1807
|
+
</div>
|
|
1808
|
+
</body>
|
|
1809
|
+
</html>
|