From e6123839d20de4f903ed74820cc087fc8401f625 Mon Sep 17 00:00:00 2001 From: Shamus Hammons Date: Mon, 13 Feb 2017 17:45:45 -0600 Subject: [PATCH] Minor tweaks to README and style guide to reflect new build system. --- README.md | 3 +- STYLE_GUIDE | 172 ++++++++++++++++++++++++++++------------------------ build.py | 6 +- 3 files changed, 95 insertions(+), 86 deletions(-) diff --git a/README.md b/README.md index 83ac658..6140834 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/STYLE_GUIDE b/STYLE_GUIDE index 09f7a6c..af78e98 100644 --- a/STYLE_GUIDE +++ b/STYLE_GUIDE @@ -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 ----------------- -,,, or any other purely visual elements are not used in -the Ardour manual. -What you really mean is an phasis or a emphasis. +,,, or any other purely visual elements are not used in the +Ardour manual. What you really mean is an phasis or a emphasis. If you feel that some special terms should always be green and underlined, the approach of choice is this: + foobar + 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 foo bar. + If you need to apply a class to several block-level elements such as paragraphs or lists, enclose them in a
..
. 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. ----------------------------

..

-A

heading is added by the Ruby framework, so it should not be used in +An

heading is added by the build script, so it should not be used in the manual page itself. If you feel you need another

, 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.

Every snippet of text should be enclosed in a block level element. The default choice is

, the plain paragraph. -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: + + + +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 tags might be used to generate an index of keywords--don't pollute it too much. -is used to explain an abbreviation such as LADSPA. 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 LADSPA. 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 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 . +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 . -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. -
-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
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!) +
+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
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 --------- -