Skip to content

Commit 6a2d8af

Browse files
acabalacabal
committed
Initial commit
0 parents  commit 6a2d8af

16 files changed

+5351
-0
lines changed

‎1-code-style.rst

+311
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,311 @@
1+
##############################
2+
XHTML, CSS, and SVG Code Style
3+
##############################
4+
5+
The :bash:`se clean` tool in the `Standard Ebooks toolset <https://github.com/standardebooks/tools>`__ formats XHTML, CSS, and SVG code according to our style guidelines. The vast majority of the time its output is correct and no further modifications to code style are necessary.
6+
7+
XHTML formatting
8+
****************
9+
10+
#. The first line of all XHTML files is:
11+
12+
.. code:: html
13+
14+
<?xml version="1.0" encoding="utf-8"?>
15+
16+
#. The second line of all XHTML files is (replace :html:`xml:lang="en-US"` with the `appropriate language tag <https://en.wikipedia.org/wiki/IETF_language_tag>`__ for the file):
17+
18+
.. code:: html
19+
20+
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" epub:prefix="z3998: http://www.daisy.org/z3998/2012/vocab/structure/, se: https://standardebooks.org/vocab/1.0" xml:lang="en-US">
21+
22+
#. Tabs are used for indentation.
23+
24+
#. Tag names are lowercase.
25+
26+
#. Elements whose content is `phrasing content <https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Content_categories#Phrasing_content>`__ are on a single line, with no whitespace between the opening and closing tags and the content.
27+
28+
.. class:: wrong
29+
30+
.. code:: html
31+
32+
<p>
33+
It was a dark and stormy night...
34+
</p>
35+
36+
.. class:: corrected
37+
38+
.. code:: html
39+
40+
<p>It was a dark and stormy night...</p>
41+
42+
:html:`<br/>` elements
43+
======================
44+
45+
#. :html:`<br/>` elements within `phrasing content <https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Content_categories#Phrasing_content>`__ are on the same line as the preceding phrasing content, and are followed by a newline.
46+
47+
.. class:: wrong
48+
49+
.. code:: html
50+
51+
<p>“Pray for the soul of the
52+
<br/>
53+
Demoiselle Jeanne D’Ys.</p>
54+
55+
.. class:: wrong
56+
57+
.. code:: html
58+
59+
<p>“Pray for the soul of the
60+
<br/>Demoiselle Jeanne D’Ys.</p>
61+
62+
.. class:: corrected
63+
64+
.. code:: html
65+
66+
<p>“Pray for the soul of the<br/>
67+
Demoiselle Jeanne D’Ys.</p>
68+
69+
#. The next indentation level after a :html:`<br/>` element is the same as the previous indentation level.
70+
71+
.. class:: wrong
72+
73+
.. code:: html
74+
75+
<p>“Pray for the soul of the<br/>
76+
Demoiselle Jeanne D’Ys,<br/>
77+
who died<br/>
78+
in her youth for love of<br/>
79+
Philip, a Stranger.</p>
80+
81+
.. class:: corrected
82+
83+
.. code:: html
84+
85+
<p>“Pray for the soul of the<br/>
86+
Demoiselle Jeanne D’Ys,<br/>
87+
who died<br/>
88+
in her youth for love of<br/>
89+
Philip, a Stranger.</p>
90+
91+
#. The closing tag of the phrasing content broken by a :html:`<br/>` element is on the same line as the last line of the phrasing content.
92+
93+
.. class:: wrong
94+
95+
.. code:: html
96+
97+
<p>“Pray for the soul of the<br/>
98+
Demoiselle Jeanne D’Ys.
99+
</p>
100+
101+
.. class:: corrected
102+
103+
.. code:: html
104+
105+
<p>“Pray for the soul of the<br/>
106+
Demoiselle Jeanne D’Ys.</p>
107+
108+
#. :html:`<br/>` elements have phrasing content both before and after; they don’t appear with phrasing content only before, or only after.
109+
110+
.. class:: wrong
111+
112+
.. code:: html
113+
114+
<p>“Pray for the soul of the<br/>
115+
Demoiselle Jeanne D’Ys<br/></p>
116+
117+
.. class:: corrected
118+
119+
.. code:: html
120+
121+
<p>“Pray for the soul of the<br/>
122+
Demoiselle Jeanne D’Ys</p>
123+
124+
Attributes
125+
==========
126+
127+
#. Attributes are in alphabetical order.
128+
129+
#. Attributes, their namespaces, and their values are lowercase, except for values which are IETF language tags. In IETF language tags, the language subtag is capitalized.
130+
131+
.. class:: wrong
132+
133+
.. code:: html
134+
135+
<section EPUB:TYPE="CHAPTER" XML:LANG="EN-US">...</section>
136+
137+
.. class:: corrected
138+
139+
.. code:: html
140+
141+
<section epub:type="chapter" xml:lang="en-US">...</section>
142+
143+
#. The string :string:`utf-8` is lowercase.
144+
145+
Classes
146+
-------
147+
148+
#. Classes are not used as one-time style hooks. There is almost always a clever selector that can be constructed instead of taking the shortcut of adding a class to an element.
149+
150+
#. Classes are named semantically, describing *what they are styling* instead of the *resulting visual style*.
151+
152+
.. class:: wrong
153+
154+
.. code:: html
155+
156+
<p>There was one great tomb more lordly than all the rest; huge it was, and nobly proportioned. On it was but one word</p>
157+
<blockquote class="small-caps">
158+
<p>Dracula.</p>
159+
</blockquote>
160+
161+
.. class:: corrected
162+
163+
.. code:: html
164+
165+
<p>There was one great tomb more lordly than all the rest; huge it was, and nobly proportioned. On it was but one word</p>
166+
<blockquote class="tomb">
167+
<p>Dracula.</p>
168+
</blockquote>
169+
170+
CSS formatting
171+
**************
172+
173+
#. The first two lines of all CSS files are:
174+
175+
.. code:: css
176+
177+
@charset "utf-8";
178+
@namespace epub "http://www.idpf.org/2007/ops";
179+
180+
#. Tabs are used for indentation.
181+
182+
#. Selectors, properties, and values are lowercase.
183+
184+
Selectors
185+
=========
186+
187+
#. Selectors are each on their own line, directly followed by a comma or a brace with no whitespace in between.
188+
189+
.. class:: wrong
190+
191+
.. code:: css
192+
193+
abbr.era, .signature{
194+
font-variant: all-small-caps;
195+
}
196+
197+
198+
.. class:: corrected
199+
200+
.. code:: css
201+
202+
abbr.era,
203+
.signature{
204+
font-variant: all-small-caps;
205+
}
206+
207+
#. Complete selectors are separated by exactly one blank line.
208+
209+
.. class:: wrong
210+
211+
.. code:: css
212+
213+
abbr.era{
214+
font-variant: all-small-caps;
215+
}
216+
217+
218+
strong{
219+
font-weight: normal;
220+
font-variant: small-caps;
221+
}
222+
223+
.. class:: corrected
224+
225+
.. code:: css
226+
227+
abbr.era{
228+
font-variant: all-small-caps;
229+
}
230+
231+
strong{
232+
font-weight: normal;
233+
font-variant: small-caps;
234+
}
235+
236+
#. Closing braces are on their own line.
237+
238+
Properties
239+
==========
240+
241+
#. Properties are each on their own line (even if the selector only has one property) and indented with a single tab.
242+
243+
.. class:: wrong
244+
245+
.. code:: css
246+
247+
abbr.era{ font-variant: all-small-caps; }
248+
249+
.. class:: corrected
250+
251+
.. code:: css
252+
253+
abbr.era{
254+
font-variant: all-small-caps;
255+
}
256+
257+
#. *Where possible*, properties are in alphabetical order.
258+
259+
This isn’t always possible if a property is attempting to override a previous property in the same selector, and in some other cases.
260+
261+
#. Properties are directly followed by a colon, then a single space, then the property value.
262+
263+
.. class:: wrong
264+
265+
.. code:: css
266+
267+
blockquote{
268+
margin-left: 1em;
269+
margin-right: 1em;
270+
border:none;
271+
}
272+
273+
.. class:: corrected
274+
275+
.. code:: css
276+
277+
blockquote{
278+
margin-left: 1em;
279+
margin-right: 1em;
280+
border: none;
281+
}
282+
283+
#. Property values are directly followed by a semicolon, even if it’s the last value in a selector.
284+
285+
.. class:: wrong
286+
287+
.. code:: css
288+
289+
abbr.era{
290+
font-variant: all-small-caps
291+
}
292+
293+
.. class:: corrected
294+
295+
.. code:: css
296+
297+
abbr.era{
298+
font-variant: all-small-caps;
299+
}
300+
301+
SVG Formatting
302+
**************
303+
304+
#. SVG formatting follows the same directives as `XHTML formatting </manual/VERSION/1-code-style#1.1>`__.
305+
306+
Commits and Commit Messages
307+
***************************
308+
309+
#. Commits are broken into single units of work. A single unit of work may be, for example, "fixing typos across 10 files", or "adding cover art", or "working on metadata".
310+
311+
#. Commits that introduce material changes to the ebook text (for example modernizing spelling or fixing a probable printer’s typo; but not fixing a transcriber’s typo) are prefaced with the string :string:`[Editorial]`, followed by a space, then the commit message. This makes it easy to search the repo history for commits that make editorial changes to the work.

0 commit comments

Comments
 (0)