Minor tweaks to README and style guide to reflect new build system.
This commit is contained in:
parent
661c9cf9df
commit
e6123839d2
|
@ -97,6 +97,5 @@ internet access. You will need `git`, and `python` installed.
|
||||||
|
|
||||||
### Helper scripts: `implode` and `explode`
|
### Helper scripts: `implode` and `explode`
|
||||||
|
|
||||||
The `implode` and `explode` scripts exist in order to accomodate different working styles. `implode` takes all the files referenced by the `include` keywords in the headers in the Master Document and automagically puts them into the Master Document in their proper places. Note that any header that has an `exclude` keyword will remain in the `include/` directory. `explode` does the inverse of `implode`; it takes all the content in the Master Document and blows it into individual files in the `include/` directory. Filenames are automagically derived from the value of the `title` keyword.
|
The `implode` and `explode` scripts exist in order to accomodate different working styles. `implode` takes all the files referenced by the `include` keywords in the headers in the Master Document and automagically puts them into the Master Document in their proper places. Note that any header that has an `exclude` keyword will remain in the `include/` directory. `explode` does the inverse of `implode`; it takes all the content in the Master Document and blows it into individual files in the `include/` directory.
|
||||||
|
|
||||||
|
|
||||||
|
|
172
STYLE_GUIDE
172
STYLE_GUIDE
|
@ -1,38 +1,41 @@
|
||||||
*Style guide for the Ardour manual*
|
|
||||||
|
|
||||||
|
*Style guide for the Ardour manual*
|
||||||
|
|
||||||
|
|
||||||
1. Rationale
|
1. Rationale
|
||||||
============
|
============
|
||||||
|
|
||||||
The Ardour manual should be consistent across different media, and it should
|
The Ardour manual should be consistent across different media, and it should
|
||||||
be easily updatable when Ardour's behaviour changes.
|
be easily updatable when Ardour's behaviour changes. The markup should be
|
||||||
The markup should be semantic - looks are determined in the CSS, and only
|
semantic--looks are determined in the CSS, and only there. If you feel you must
|
||||||
there. If you feel you must compromise the markup in order to obtain a
|
compromise the markup in order to obtain a certain look: don't do it. Accept
|
||||||
certain look: don't do it. Accept the look.
|
the look. Alternatively, edit the CSS, but be careful not to make matters worse
|
||||||
Alternatively, edit the CSS, but be careful not to make matters worse
|
|
||||||
elsewhere.
|
elsewhere.
|
||||||
|
|
||||||
|
|
||||||
1.1 visual markup
|
1.1 visual markup
|
||||||
-----------------
|
-----------------
|
||||||
|
|
||||||
<b>,<i>,<u>,<font> or any other purely visual elements are not used in
|
<b>,<i>,<u>,<font> or any other purely visual elements are not used in the
|
||||||
the Ardour manual.
|
Ardour manual. What you really mean is an <em>phasis or a <strong> emphasis.
|
||||||
What you really mean is an <em>phasis or a <strong> emphasis.
|
|
||||||
If you feel that some special terms should always be green and underlined, the
|
If you feel that some special terms should always be green and underlined, the
|
||||||
approach of choice is this:
|
approach of choice is this:
|
||||||
|
|
||||||
<span class="my_important_keyword">foobar</span>
|
<span class="my_important_keyword">foobar</span>
|
||||||
|
|
||||||
and then add
|
and then add
|
||||||
|
|
||||||
.my_important_keyword {
|
.my_important_keyword {
|
||||||
text-decoration: underline;
|
text-decoration: underline;
|
||||||
color: #004400;
|
color: #004400;
|
||||||
background-color: #eeffee;
|
background-color: #eeffee;
|
||||||
}
|
}
|
||||||
|
|
||||||
to apps.css.
|
to apps.css.
|
||||||
|
|
||||||
If you add a new class with semantic meaning, document it below, under
|
If you add a new class with semantic meaning, document it below, under
|
||||||
"Custom classes", and be sure to explain it to the reader at
|
"Custom classes", and be sure to explain it to the reader at
|
||||||
_manual/01_welcome-to-ardour/02_about-ardour-documentation.html.
|
include/about-ardour-documentation.html.
|
||||||
|
|
||||||
|
|
||||||
2. Format and Validation
|
2. Format and Validation
|
||||||
|
@ -58,6 +61,7 @@ semantic markup than core XHTML allows.
|
||||||
Any XHTML element can include a class attribute. If you need to add a class
|
Any XHTML element can include a class attribute. If you need to add a class
|
||||||
attribute to a word or a few words which don't have an element of their own,
|
attribute to a word or a few words which don't have an element of their own,
|
||||||
use <span class="my_new_category">foo bar</span>.
|
use <span class="my_new_category">foo bar</span>.
|
||||||
|
|
||||||
If you need to apply a class to several block-level elements such as
|
If you need to apply a class to several block-level elements such as
|
||||||
paragraphs or lists, enclose them in a <div>..</div>. Wherever possible,
|
paragraphs or lists, enclose them in a <div>..</div>. Wherever possible,
|
||||||
create semantic classes rather than visual ones.
|
create semantic classes rather than visual ones.
|
||||||
|
@ -80,8 +84,8 @@ or sound quality issues. Currently rendered in a red box.
|
||||||
use as additional classes to mark a section as relevant for these operating
|
use as additional classes to mark a section as relevant for these operating
|
||||||
systems only.
|
systems only.
|
||||||
|
|
||||||
Check _manual/01_welcome-to-ardour/02_about-ardour-documentation.html, it
|
Check include/about-ardour-documentation.html, it serves as a style and
|
||||||
serves as a style and markup guide.
|
markup guide.
|
||||||
|
|
||||||
|
|
||||||
4. Element use
|
4. Element use
|
||||||
|
@ -92,21 +96,29 @@ serves as a style and markup guide.
|
||||||
----------------------------
|
----------------------------
|
||||||
|
|
||||||
<h1>..<h6>
|
<h1>..<h6>
|
||||||
A <h1/> heading is added by the Ruby framework, so it should not be used in
|
An <h1/> heading is added by the build script, so it should not be used in
|
||||||
the manual page itself. If you feel you need another <h1>, start a new
|
the manual page itself. If you feel you need another <h1>, start a new
|
||||||
subpage.
|
subpage. Heading levels must not be skipped. Any sub-heading must be exactly
|
||||||
Heading levels must not be skipped. Any sub-heading must be exactly one
|
one level below its predecessor. Do not abuse headings to style a head line.
|
||||||
level below its predecessor. Do not abuse headings to style a head line.
|
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
Every snippet of text should be enclosed in a block level element. The
|
Every snippet of text should be enclosed in a block level element. The
|
||||||
default choice is <p>, the plain paragraph.
|
default choice is <p>, the plain paragraph.
|
||||||
|
|
||||||
<a>
|
<a>
|
||||||
Cross-reference links in the manual are reasonably stable, since they are
|
Internal manual links should be absolutely stable, as long as the references in
|
||||||
independent of the ordering number (which gets removed from the URL) and the
|
the master document do not change (and they absolutely *should* not be changed
|
||||||
pretty page title (the URL is created from the file name). So unless a file
|
except for a *very* good reason, even then they probably should not be
|
||||||
is renamed or moved to another sub-directory, links should be ok.
|
changed!). Use the form:
|
||||||
|
|
||||||
|
<a href="@@my-internal-link">
|
||||||
|
|
||||||
|
where @@my-internal-link is a reference to a "link:" keyword in a header in the
|
||||||
|
master document. Note that in the master document, they will not have the
|
||||||
|
double at-sign ("@@") in front, that is *only* used in the page content to
|
||||||
|
signal to the build system that it is an internal link that needs to be fixed
|
||||||
|
so that it points to the correct URL.
|
||||||
|
|
||||||
|
|
||||||
4.1 Inline markups
|
4.1 Inline markups
|
||||||
------------------
|
------------------
|
||||||
|
@ -119,40 +131,39 @@ in mind that <dfn> tags might be used to generate an index of keywords--don't
|
||||||
pollute it too much.
|
pollute it too much.
|
||||||
|
|
||||||
<abbr>
|
<abbr>
|
||||||
is used to explain an abbreviation such as <abbr title="Linux Audio
|
is used to explain an abbreviation such as <abbr title="Linux Audio Developers
|
||||||
Developers Simple Plugin API">LADSPA</abbr>. Browsers will usually pop up the
|
Simple Plugin API">LADSPA</abbr>. Browsers will usually pop up the definition
|
||||||
definition when the user hovers over the word. Renders as dotted underlined
|
when the user hovers over the word. Renders as dotted underlined in most
|
||||||
in most browsers.
|
browsers. On each page, use only for the first occurrence of every
|
||||||
On each page, use only for the first occurrence of every abbreviation. Avoid
|
abbreviation. Avoid a redundant explanation in the text--the expansion can
|
||||||
a redundant explanation in the text--the expansion can easily be extracted
|
easily be extracted via CSS for printing. Use only in the text body, not in
|
||||||
via CSS for printing.
|
headings.
|
||||||
Use only in the text body, not in headings.
|
|
||||||
|
|
||||||
<em>
|
<em>
|
||||||
is used to emphasize a word. Commonly rendered as italics.
|
is used to emphasize a word. Commonly rendered as italics. Use only if its a
|
||||||
Use only if its a truly ad-hoc, one-off situation. For anything else,
|
truly ad-hoc, one-off situation. For anything else, consider adding a new
|
||||||
consider adding a new semantic markup with <span class="foo">.
|
semantic markup with <span class="foo">.
|
||||||
|
|
||||||
<strong>
|
<strong>
|
||||||
is used to strongly emphasize a word. Commonly rendered in bold.
|
is used to strongly emphasize a word. Commonly rendered in bold. See above for
|
||||||
See above for usage.
|
usage.
|
||||||
|
|
||||||
<br />
|
<br>
|
||||||
Most of the time, these should be avoided, and used very infrequently.
|
Most of the time, these should be avoided, and used very infrequently. A line-
|
||||||
A line-break can sometimes be used to structure a paragraph, or to split a
|
break can sometimes be used to structure a paragraph, or to split a longish
|
||||||
longish heading. Never use spurious <br/>s at the end of paragraphs or to
|
heading. Never use spurious <br>s at the end of paragraphs or to control the
|
||||||
control the spacing of sections. If you're unhappy with those, fix the CSS
|
spacing of sections. If you're unhappy with those, fix the CSS (which fixes the
|
||||||
(which fixes the entire manual in one go!)
|
entire manual in one go!).
|
||||||
|
|
||||||
|
|
||||||
4.2 Lists
|
4.2 Lists
|
||||||
---------
|
---------
|
||||||
|
|
||||||
<ul>,<ol>
|
<ul>, <ol>
|
||||||
Use the unordered list for information snippets that do not have an implied
|
Use the unordered list for information snippets that do not have an implied
|
||||||
order. The ordered list should always be used when a sequence of actions is
|
order. The ordered list should always be used when a sequence of actions is
|
||||||
described. Within the lists, each item must be enclosed in <li> tags.
|
described. Within the lists, each item must be enclosed in <li> tags. Lists
|
||||||
Lists cannot be included in <p>aragraphs. Close the paragraph first.
|
cannot be included in <p>aragraphs. Close the paragraph first.
|
||||||
|
|
||||||
<dl>
|
<dl>
|
||||||
Definition lists are for technical terms <dt> and their definition <dd>. Do
|
Definition lists are for technical terms <dt> and their definition <dd>. Do
|
||||||
|
@ -163,34 +174,35 @@ not abuse them for anything else.
|
||||||
--------------
|
--------------
|
||||||
|
|
||||||
<blockquote>
|
<blockquote>
|
||||||
is used when an entire paragraph is quoted. Must contain a
|
is used when an entire paragraph is quoted. Must contain a cite="http://
|
||||||
cite="http://mysource.net/foo.pdf" attribute. Do not abuse to indent a
|
mysource.net/foo.pdf" attribute. Do not abuse to indent a paragraph!
|
||||||
paragraph!
|
|
||||||
|
|
||||||
<cite>,<q>
|
<cite>, <q>
|
||||||
For inline citations, the <cite>W3C</cite> recommends to <q
|
For inline citations, the <cite>W3C</cite> recommends to <q cite="http://
|
||||||
cite="http://www.w3.org/TR/xhtml1/dtds.html">use the cite and q
|
www.w3.org/TR/xhtml1/dtds.html">use the cite and q elements</q>.
|
||||||
elements</q>.
|
|
||||||
|
|
||||||
|
|
||||||
4.4 Keyboard/Controller interaction
|
4.4 Keyboard/Controller interaction
|
||||||
------------------------------------
|
-----------------------------------
|
||||||
|
|
||||||
<kbd>
|
<kbd>
|
||||||
Any keys or key combinations, mouse buttons or controllers, menu items or
|
Any keys or key combinations, mouse buttons or controllers, menu items or
|
||||||
textual user input should be marked with this element. It is used here in
|
textual user input should be marked with this element. It is used here in
|
||||||
the widest possible sense, qualified by classes.
|
the widest possible sense, qualified by classes. E.g.:
|
||||||
E.g.:
|
|
||||||
"Press <kbd>f</kbd> to fit all tracks to the height of the Editor window."
|
"Press <kbd>f</kbd> to fit all tracks to the height of the Editor window."
|
||||||
"Move <kbd>Fader 1</kbd> on your MIDI controller to bind it.
|
"Move <kbd>Fader 1</kbd> on your MIDI controller to bind it."
|
||||||
"
|
|
||||||
Since modifier keys are not cross-platform and Ardour makes a point of
|
Since modifier keys are not cross-platform and Ardour makes a point of
|
||||||
abstracting them, do not hard-code "Alt", "Cmd" and friends, use
|
abstracting them, do not hard-code "Alt", "Cmd" and friends, use
|
||||||
|
|
||||||
class="modN"
|
class="modN"
|
||||||
|
|
||||||
instead.
|
instead.
|
||||||
|
|
||||||
So if you want the user to press Ctrl-N on Linux, that's actually <kbd
|
So if you want the user to press Ctrl-N on Linux, that's actually <kbd
|
||||||
class="mod1">N</kbd>. It will render as "Ctrl N" for you, and as "Cmd N" for
|
class="mod1">N</kbd>. It will render as "Ctrl N" for you, and as "Cmd N" for
|
||||||
your Mac-using friend. Nice, uh?
|
your Mac-using friend. Nice, huh?
|
||||||
|
|
||||||
N.B.: If you want to have just the name of the modifier key by itself, use
|
N.B.: If you want to have just the name of the modifier key by itself, use
|
||||||
<kbd class="mod1>‌</kbd> (zero-width non-joiner).
|
<kbd class="mod1>‌</kbd> (zero-width non-joiner).
|
||||||
|
@ -203,6 +215,7 @@ Keys and mouse key names should always be entered lowercase, even though the
|
||||||
stylesheet might capitalize them.
|
stylesheet might capitalize them.
|
||||||
|
|
||||||
CSS Classes used with <kbd> are:
|
CSS Classes used with <kbd> are:
|
||||||
|
|
||||||
.modN
|
.modN
|
||||||
.mouse: mouse buttons
|
.mouse: mouse buttons
|
||||||
.cmd: a command line
|
.cmd: a command line
|
||||||
|
@ -227,12 +240,10 @@ types or presses.
|
||||||
|
|
||||||
<img>
|
<img>
|
||||||
The image tag must contain a 'src="/images/yourimage.png"' element and a
|
The image tag must contain a 'src="/images/yourimage.png"' element and a
|
||||||
descriptive 'alt="A short textual description of the image content"'
|
descriptive 'alt="A short textual description of the image content"' element.
|
||||||
element.
|
Images are usually placed as block-level elements, i.e. outside of a paragraph,
|
||||||
Images are usually placed as block-level elements, i.e. outside of a
|
unless they are no higher than one row and make sense in the text flow.
|
||||||
paragraph, unless they are no higher than one row and make sense in the text
|
|
||||||
flow. Aside from this exception, they should *always* be wrapped inside of a
|
|
||||||
<p></p> block.
|
|
||||||
|
|
||||||
5. Other conventions
|
5. Other conventions
|
||||||
====================
|
====================
|
||||||
|
@ -245,8 +256,8 @@ flow. Aside from this exception, they should *always* be wrapped inside of a
|
||||||
kind of subtle inflection, use semantic markup instead.
|
kind of subtle inflection, use semantic markup instead.
|
||||||
* The hyphen is used to for compound words such as this well-advised example.
|
* The hyphen is used to for compound words such as this well-advised example.
|
||||||
* Do not hyphenate words at line breaks.
|
* Do not hyphenate words at line breaks.
|
||||||
* For breaks in thought—such as this splendid example—use
|
* For breaks in thought—such as this splendid example—use the long
|
||||||
the long em-dash. Note that the em-dash is snugged up against the text on both
|
em-dash. Note that the em-dash is snugged up against the text on both
|
||||||
sides--this is the proper way to use them.
|
sides--this is the proper way to use them.
|
||||||
* For ranges of values, use the en-dash: Monday–Friday, 0–11. Note
|
* For ranges of values, use the en-dash: Monday–Friday, 0–11. Note
|
||||||
again, the en-dash is snugged up to its surrounding elements.
|
again, the en-dash is snugged up to its surrounding elements.
|
||||||
|
@ -262,7 +273,7 @@ flow. Aside from this exception, they should *always* be wrapped inside of a
|
||||||
* Use SI units with standard abbreviations. Give imperial units only as
|
* Use SI units with standard abbreviations. Give imperial units only as
|
||||||
additional information, if at all.
|
additional information, if at all.
|
||||||
* Do not use contractions like "it'll", always write full forms.
|
* Do not use contractions like "it'll", always write full forms.
|
||||||
* Do not over-use "You", write about the program, not the user. Avoid it if at
|
* Do not over-use "You"; write about the program, not the user. Avoid it if at
|
||||||
all possible, it makes for tighter and better reading text.
|
all possible, it makes for tighter and better reading text.
|
||||||
* Always write out numbers less than 11. E.g., "One or two ..." instead of
|
* Always write out numbers less than 11. E.g., "One or two ..." instead of
|
||||||
"1 or 2 ...".
|
"1 or 2 ...".
|
||||||
|
@ -272,8 +283,7 @@ flow. Aside from this exception, they should *always* be wrapped inside of a
|
||||||
------------------------------------
|
------------------------------------
|
||||||
|
|
||||||
Capitalization follows
|
Capitalization follows
|
||||||
https://developer.gnome.org/hig-book/3.6/design-text-labels.html.en#layout-capitalization
|
https://developer.gnome.org/hig-book/3.6/design-text-labels.html.en#layout-capitalization:
|
||||||
:
|
|
||||||
|
|
||||||
* Capitalize all words in the headline, with the following exceptions:
|
* Capitalize all words in the headline, with the following exceptions:
|
||||||
Articles: a, an, the.
|
Articles: a, an, the.
|
||||||
|
@ -288,35 +298,37 @@ https://developer.gnome.org/hig-book/3.6/design-text-labels.html.en#layout-capit
|
||||||
5.4 Janitorial tasks/review
|
5.4 Janitorial tasks/review
|
||||||
---------------------------
|
---------------------------
|
||||||
|
|
||||||
If you encounter something that is unclear or patent nonsense, but you are
|
If you encounter something that is unclear or patent nonsense, but you are not
|
||||||
not bold or knowledgeable to fix it, express your doubts with an <p
|
bold or knowledgeable to fix it, express your doubts with an <p
|
||||||
class="fixme">editorial note</p>, so that readers will be warned and fellow
|
class="fixme">editorial note</p>, so that readers will be warned and fellow
|
||||||
editors know where there's work to do.
|
editors know where there's work to do.
|
||||||
|
|
||||||
|
|
||||||
5.5 Writing style suggestions
|
5.5 Writing style suggestions
|
||||||
-----------------------------
|
-----------------------------
|
||||||
|
|
||||||
* "Click OK" and similar explanations of the utterly obvious should be
|
* "Click OK" and similar explanations of the utterly obvious should be
|
||||||
avoided. Keep the writing concise and to the point. Explain as much as
|
avoided. Keep the writing concise and to the point. Explain as much as
|
||||||
possible, with as few words as possible.
|
possible, with as few words as possible.
|
||||||
* Do not fear repetitions, this is not artistic prose. Repeat important
|
* Do not fear repetitions, this is not artistic prose. Repeat important
|
||||||
keywords, rather than burden the user with synonyms made up on the spot.
|
keywords, rather than burden the user with synonyms made up on the spot.
|
||||||
* Do not create headings for different ways of doing the same thing (<h>Via
|
* Do not create headings for different ways of doing the same thing (<h>Via
|
||||||
the context menu</h>,...<h>Via hotkeys</h>). Headings separate new
|
the context menu</h>,...<h>Via hotkeys</h>). Headings separate new
|
||||||
concepts. To not add gratuitous sub-headings if there is very little
|
concepts. To not add gratuitous sub-headings if there is very little
|
||||||
content per heading and you do not expect the article to grow.
|
content per heading and you do not expect the article to grow.
|
||||||
* If pages grow long, consider splitting them into sub-chapters at their
|
* If pages grow long, consider splitting them into sub-chapters at their
|
||||||
headings.
|
headings.
|
||||||
* Nobody needs "the next paragraph is about the following" paragraphs.
|
* Nobody needs "the next paragraph is about the following" paragraphs.
|
||||||
* When creating a <p class="note">NOTE</p>, *do not* put the word NOTE into
|
* When creating a <p class="note">NOTE</p>, *do not* put the word NOTE into
|
||||||
the note, the styling tells the user that it is a note.
|
the note, the styling tells the user that it is a note.
|
||||||
|
|
||||||
|
|
||||||
5.6. Encoding
|
5.6. Encoding
|
||||||
-------------
|
-------------
|
||||||
|
|
||||||
* Pages should be encoded in UTF-8, with Unix-style newlines if possible
|
* Pages should be encoded in UTF-8, with Unix-style newlines if possible
|
||||||
(although that's not critical). Avoid using verbatim special symbols, use
|
(although that's not critical). Avoid using verbatim special symbols, use
|
||||||
HTML character entities instead, for example for cursor arrows: →
|
HTML character entities instead, for example for cursor arrows: →
|
||||||
← ↑ ↓. Diacriticals on vowels and other special letters are
|
← ↑ ↓. Diacriticals on vowels and other special letters are
|
||||||
probably ok by now, so don't bother with é and friends, just type é.
|
probably ok by now, so don't bother with é and friends, just type é.
|
||||||
|
|
||||||
|
|
6
build.py
6
build.py
|
@ -466,10 +466,8 @@ for header in fileStruct:
|
||||||
page = page.replace('{% prevnext %}', prevnext)
|
page = page.replace('{% prevnext %}', prevnext)
|
||||||
page = page.replace('{{ content }}', content + more)
|
page = page.replace('{{ content }}', content + more)
|
||||||
|
|
||||||
# Create the directory for the index.html file to go into
|
# Create the directory for the index.html file to go into (we use makedirs,
|
||||||
# (we use makedirs, because we have to in order to accomadate the 'uri'
|
# because we have to in order to accomodate the 'uri' keyword)
|
||||||
# keyword
|
|
||||||
# os.mkdir(siteDir + header['filename'], 0o775)
|
|
||||||
os.makedirs(siteDir + header['filename'], 0o775, exist_ok=True)
|
os.makedirs(siteDir + header['filename'], 0o775, exist_ok=True)
|
||||||
|
|
||||||
# Finally, write the file!
|
# Finally, write the file!
|
||||||
|
|
Loading…
Reference in New Issue