ardour
/
manual
13
0
Fork 0
Code Pull Requests Releases Activity

Minor tweaks to README and style guide to reflect new build system.

This commit is contained in:
Shamus Hammons 2017-02-13 17:45:45 -06:00
parent 661c9cf9df
commit e6123839d2
3 changed files with 95 additions and 86 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
README.md
View File

@ -97,6 +97,5 @@ internet access. You will need `git`, and `python` installed.
### 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
View File

@ -1,38 +1,41 @@
*Style guide for the Ardour manual*
*Style guide for the Ardour manual*
1. Rationale
============
The Ardour manual should be consistent across different media, and it should
be easily updatable when Ardour's behaviour changes.
The markup should be semantic - looks are determined in the CSS, and only
there. If you feel you must compromise the markup in order to obtain a
certain look: don't do it. Accept the look.
Alternatively, edit the CSS, but be careful not to make matters worse
be easily updatable when Ardour's behaviour changes. The markup should be
semantic--looks are determined in the CSS, and only there. If you feel you must
compromise the markup in order to obtain a certain look: don't do it. Accept
the look. Alternatively, edit the CSS, but be careful not to make matters worse
elsewhere.
1.1 visual markup
-----------------
<b>,<i>,<u>,<font> or any other purely visual elements are not used in
the Ardour manual.
What you really mean is an <em>phasis or a <strong> emphasis.
<b>,<i>,<u>,<font> or any other purely visual elements are not used in the
Ardour manual. 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
approach of choice is this:
<span class="my_important_keyword">foobar</span>
and then add
.my_important_keyword {
text-decoration: underline;
color: #004400;
background-color: #eeffee;
}
to apps.css.
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
_manual/01_welcome-to-ardour/02_about-ardour-documentation.html.
include/about-ardour-documentation.html.
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
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>.
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,
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
systems only.
Check _manual/01_welcome-to-ardour/02_about-ardour-documentation.html, it
serves as a style and markup guide.
Check include/about-ardour-documentation.html, it serves as a style and
markup guide.
4. Element use
@ -92,21 +96,29 @@ serves as a style and markup guide.
----------------------------
<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
subpage.
Heading levels must not be skipped. Any sub-heading must be exactly one
level below its predecessor. Do not abuse headings to style a head line.
subpage. Heading levels must not be skipped. Any sub-heading must be exactly
one level below its predecessor. Do not abuse headings to style a head line.
<p>
Every snippet of text should be enclosed in a block level element. The
default choice is <p>, the plain paragraph.
<a>
Cross-reference links in the manual are reasonably stable, since they are
independent of the ordering number (which gets removed from the URL) and the
pretty page title (the URL is created from the file name). So unless a file
is renamed or moved to another sub-directory, links should be ok.
Internal manual links should be absolutely stable, as long as the references in
the master document do not change (and they absolutely *should* not be changed
except for a *very* good reason, even then they probably should not be
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
------------------
@ -119,40 +131,39 @@ in mind that <dfn> tags might be used to generate an index of keywords--don't
pollute it too much.
<abbr>
is used to explain an abbreviation such as <abbr title="Linux Audio
Developers Simple Plugin API">LADSPA</abbr>. Browsers will usually pop up the
definition when the user hovers over the word. Renders as dotted underlined
in most browsers.
On each page, use only for the first occurrence of every abbreviation. Avoid
a redundant explanation in the text--the expansion can easily be extracted
via CSS for printing.
Use only in the text body, not in headings.
is used to explain an abbreviation such as <abbr title="Linux Audio Developers
Simple Plugin API">LADSPA</abbr>. Browsers will usually pop up the definition
when the user hovers over the word. Renders as dotted underlined in most
browsers. On each page, use only for the first occurrence of every
abbreviation. Avoid a redundant explanation in the text--the expansion can
easily be extracted via CSS for printing. Use only in the text body, not in
headings.
<em>
is used to emphasize a word. Commonly rendered as italics.
Use only if its a truly ad-hoc, one-off situation. For anything else,
consider adding a new semantic markup with <span class="foo">.
is used to emphasize a word. Commonly rendered as italics. Use only if its a
truly ad-hoc, one-off situation. For anything else, consider adding a new
semantic markup with <span class="foo">.
<strong>
is used to strongly emphasize a word. Commonly rendered in bold.
See above for usage.
is used to strongly emphasize a word. Commonly rendered in bold. See above for
usage.
<br />
Most of the time, these should be avoided, and used very infrequently.
A line-break can sometimes be used to structure a paragraph, or to split a
longish heading. Never use spurious <br/>s at the end of paragraphs or to
control the spacing of sections. If you're unhappy with those, fix the CSS
(which fixes the entire manual in one go!)
<br>
Most of the time, these should be avoided, and used very infrequently. A line-
break can sometimes be used to structure a paragraph, or to split a longish
heading. Never use spurious <br>s at the end of paragraphs or to control the
spacing of sections. If you're unhappy with those, fix the CSS (which fixes the
entire manual in one go!).
4.2 Lists
---------
<ul>,<ol>
<ul>, <ol>
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
described. Within the lists, each item must be enclosed in <li> tags.
Lists cannot be included in <p>aragraphs. Close the paragraph first.
described. Within the lists, each item must be enclosed in <li> tags. Lists
cannot be included in <p>aragraphs. Close the paragraph first.
<dl>
Definition lists are for technical terms <dt> and their definition <dd>. Do
@ -163,34 +174,35 @@ not abuse them for anything else.
--------------
<blockquote>
is used when an entire paragraph is quoted. Must contain a
cite="http://mysource.net/foo.pdf" attribute. Do not abuse to indent a
paragraph!
is used when an entire paragraph is quoted. Must contain a cite="http://
mysource.net/foo.pdf" attribute. Do not abuse to indent a paragraph!
<cite>,<q>
For inline citations, the <cite>W3C</cite> recommends to <q
cite="http://www.w3.org/TR/xhtml1/dtds.html">use the cite and q
elements</q>.
<cite>, <q>
For inline citations, the <cite>W3C</cite> recommends to <q cite="http://
www.w3.org/TR/xhtml1/dtds.html">use the cite and q elements</q>.
4.4 Keyboard/Controller interaction
------------------------------------
4.4 Keyboard/Controller interaction
-----------------------------------
<kbd>
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
the widest possible sense, qualified by classes.
E.g.:
the widest possible sense, qualified by classes. E.g.:
"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
abstracting them, do not hard-code "Alt", "Cmd" and friends, use
class="modN"
instead.
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
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
<kbd class="mod1>&zwnj;</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.
CSS Classes used with <kbd> are:
.modN
.mouse: mouse buttons
.cmd: a command line
@ -227,12 +240,10 @@ types or presses.
<img>
The image tag must contain a 'src="/images/yourimage.png"' element and a
descriptive 'alt="A short textual description of the image content"'
element.
Images are usually placed as block-level elements, i.e. outside of a
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.
descriptive 'alt="A short textual description of the image content"' element.
Images are usually placed as block-level elements, i.e. outside of a paragraph,
unless they are no higher than one row and make sense in the text flow.
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.
* The hyphen is used to for compound words such as this well-advised example.
* Do not hyphenate words at line breaks.
* For breaks in thought&mdash;such as this splendid example&mdash;use
the long em-dash. Note that the em-dash is snugged up against the text on both
* For breaks in thought&mdash;such as this splendid example&mdash;use the long
em-dash. Note that the em-dash is snugged up against the text on both
sides--this is the proper way to use them.
* For ranges of values, use the en-dash: Monday&ndash;Friday, 0&ndash;11. Note
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
additional information, if at all.
* 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.
* Always write out numbers less than 11. E.g., "One or two ..." instead of
"1 or 2 ...".
@ -272,8 +283,7 @@ flow. Aside from this exception, they should *always* be wrapped inside of a
------------------------------------
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:
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
---------------------------
If you encounter something that is unclear or patent nonsense, but you are
not bold or knowledgeable to fix it, express your doubts with an <p
If you encounter something that is unclear or patent nonsense, but you are not
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
editors know where there's work to do.
5.5 Writing style suggestions
-----------------------------
* "Click OK" and similar explanations of the utterly obvious should be
avoided. Keep the writing concise and to the point. Explain as much as
possible, with as few words as possible.
avoided. Keep the writing concise and to the point. Explain as much as
possible, with as few words as possible.
* 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
the context menu</h>,...<h>Via hotkeys</h>). Headings separate new
concepts. To not add gratuitous sub-headings if there is very little
content per heading and you do not expect the article to grow.
the context menu</h>,...<h>Via hotkeys</h>). Headings separate new
concepts. To not add gratuitous sub-headings if there is very little
content per heading and you do not expect the article to grow.
* If pages grow long, consider splitting them into sub-chapters at their
headings.
headings.
* 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
the note, the styling tells the user that it is a note.
5.6. Encoding
-------------
* Pages should be encoded in UTF-8, with Unix-style newlines if possible
(although that's not critical). Avoid using verbatim special symbols, use
HTML character entities instead, for example for cursor arrows: &rarr;
&larr; &uarr; &darr;. Diacriticals on vowels and other special letters are
probably ok by now, so don't bother with &eacute; and friends, just type é.
(although that's not critical). Avoid using verbatim special symbols, use
HTML character entities instead, for example for cursor arrows: &rarr;
&larr; &uarr; &darr;. Diacriticals on vowels and other special letters are
probably ok by now, so don't bother with &eacute; and friends, just type é.

6
build.py
View File

@ -466,10 +466,8 @@ for header in fileStruct:
page = page.replace('{% prevnext %}', prevnext)
page = page.replace('{{ content }}', content + more)
# Create the directory for the index.html file to go into
# (we use makedirs, because we have to in order to accomadate the 'uri'
# keyword
# os.mkdir(siteDir + header['filename'], 0o775)
# Create the directory for the index.html file to go into (we use makedirs,
# because we have to in order to accomodate the 'uri' keyword)
os.makedirs(siteDir + header['filename'], 0o775, exist_ok=True)
# Finally, write the file!