From 3091d900ad0f052e0f57f41e2213d09313a40dd8 Mon Sep 17 00:00:00 2001 From: Shamus Hammons Date: Mon, 16 Jan 2017 20:24:04 -0600 Subject: [PATCH] Update to style guide and README. --- README.md | 19 +++++++++++++++++-- STYLE_GUIDE | 38 ++++++++++++++++++++++++++------------ 2 files changed, 43 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index dadce20..fd61c3b 100644 --- a/README.md +++ b/README.md @@ -67,8 +67,8 @@ Content processing is applied to normal content if it has the correct header as Three types of content can have special processing done. - `.html` liquid/HTML files -- `.md` markdown files -- `.textile` textile files +- `.md` markdown files (NOPE!) +- `.textile` textile files (NOPE!) All files to be processed should also have a special header at the top too: @@ -113,6 +113,7 @@ internet access. You will need `git`, `ruby`, and the ruby gem `liquid` installe 2. open `ardour-manual/_site/index.html` in your favorite web browser If this page doesn't open and function correctly, follow these optional steps to serve up the page with nginx. + N.B.: Step 2 will *never* work; you *must* install nginx if you want to see it! 3. Install [nginx](http://wiki.nginx.org/Install) 4. Configure nginx server block in `/etc/nginx/sites-available/default` @@ -147,6 +148,20 @@ E.g. `02_main/05_more/02_blah.html` after all processing is complete would end u The page format contained in the `_manual/` directory is different to the final rendered output (see special `_manual` content above) to make it simple to create content (you don't need to think about the `index.html` files). +### New Stuff +The above will have to be revised eventually, but for now, here's what's what: + +1. All content lives in master-doc.txt and in include/ . + +2. A little C helper program needs to be built and run. To build it, do: + + gcc munge.cpp -o munge -lstdc++ -g + +3. Run the 'doit' script: + + ./doit + +4. Now _site/ should contain the correct built site. Have fun! ;-) diff --git a/STYLE_GUIDE b/STYLE_GUIDE index be65d63..09f7a6c 100644 --- a/STYLE_GUIDE +++ b/STYLE_GUIDE @@ -114,9 +114,9 @@ is renamed or moved to another sub-directory, links should be ok. encloses a newly introduced term that is being explained. Use for the first occurrence of the main concept of every manual page, or the first occurrence -of a new concept after a sub-heading if necessary. Renders in bold face. -Keep in mind that tags might be used to generate an index of keywords -- don't pollute it too much. +of a new concept after a sub-heading if necessary. Renders in bold face. Keep +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 +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. @@ -138,6 +138,7 @@ 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 @@ -191,6 +192,9 @@ So if you want the user to press Ctrl-N on Linux, that's actually N. It will render as "Ctrl N" for you, and as "Cmd N" for your Mac-using friend. Nice, uh? +N.B.: If you want to have just the name of the modifier key by itself, use +

block. 5. Other conventions ==================== @@ -240,21 +245,27 @@ flow. 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 — such as this splendid example — use - the long em-dash. -* For ranges of values, use the en-dash: Monday – Friday, 0 – - 11. +* For breaks in thought—such as this splendid example—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–Friday, 0–11. Note + again, the en-dash is snugged up to its surrounding elements. * Use a non-breaking space (" ") between a number and its unit. +* Colons (":") always snug up to their text on the left: it is an error to add + space between text on the left and the colon. 5.2 Language ------------ -* The Ardour manual is written in Americal English spelling. +* The Ardour manual is written in American English spelling. * Use SI units with standard abbreviations. Give imperial units only as additional information, if at all. -* Do not use contractions like "you'll", always write full forms. -* Do not over-use "You", write about the program, not the user. +* 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 + 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 ...". 5.3 Chapter Headline Capitalization @@ -297,6 +308,8 @@ 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. * Nobody needs "the next paragraph is about the following" paragraphs. +* When creating a

NOTE

, *do not* put the word NOTE into + the note, the styling tells the user that it is a note. 5.6. Encoding ------------- @@ -306,3 +319,4 @@ headings. HTML character entities instead, for example for cursor arrows: → ← ↑ ↓. Diacriticals on vowels and other special letters are probably ok by now, so don't bother with é and friends, just type é. + -- 2.37.2