Editorial guidelines for current projects
- These are the guidelines I follow in the project files I maintain.
argument outlining
for( each file )
+ Determine the argument.
+ List the conclusions.
for( each conclusion )
+ List the premises.
+ Compose a leading summary.
/ E.g. a sentence summarizing the argument, followed by a brief elaboration if necessary.
+ Outline the argument.
- Outline according to your own lights.
- Avoid unecessary claims and commitments.
lexical order
- Order words and phrases first by letters, then by punctuation and whitespace.
/ E.g. ‘foo-bar’ and ‘foo bar’ would both appear together with ‘foobar’.
notation
italics
- To interpolate a variable placeholder, wrap between ‘<’ and ‘>’.
/ Examples:
cd <command directory>
build <project path> <target path>…
- To represent italics in other cases, wrap between between asterisks ‘*’.
quotes from technical language
/ E.g. from a programming language (source code).
/ E.g. from a data communication language, for instance a URL.
- Avoid direct inclusion in sentences of technical language constructs,
which are foreign to English.
- Instead wrap any such inclusion between grave accents ‘`’ (Unicode 60, aka backticks
or backquotes) or other quoting delimiters.
: re `grave accents` see https://en.wikipedia.org/wiki/Grave_accent#Use_in_programming
shell command syntax, formal definition
- Use the notation of Linux manual pages to define the form of particular shell commands.
: see `^*SYNOPSIS$` @ `^*Sections within a manual page$` @
https://man7.org/linux/man-pages/man7/man-pages.7.html#DESCRIPTION
stress
/ E.g. for the phonology of lexical terms.
- Place an acute (or grave) accent over the vowel to mark primary (or secondary) stress.
∵ This ‘has the advantage of not requiring a decision about syllable boundaries.’
: see https://en.wikipedia.org/wiki/Stress_(linguistics)#Spelling_and_notation_for_stress
operating system, assumption of Linux
- A project may assume that the reader is running Linux, provided it refers to this note.
: e.g. `${same}` @ http://reluk.ca/project/Makeshift/project_installation.brec
- This seems a safe assumption at present.
∵ The target users (at present) are developers.
∵ Developers who want to see support added for another operating system
are themselves the best qualified to do the work.
- Note however that Windows accepts ‘/’ in file paths as equivalent to ‘\’.
plain text
- Characters per line (aka columns): generally a limit of 105.
: see https://en.wikipedia.org/wiki/Characters_per_line
proper names
- Form them using standard case conventions.
/ So ‘Git Hub’ not ‘GitHub’,
and ‘Javascript’ not ‘JavaScript’.
/ So ‘Web Autoindex’ not ‘Web.autoindex’.
- Not all projects have proper names.
/ Witness the Breccia Web imager project, so referred to (‘the Breccia Web imager project’,
or ‘the Breccia Web imager’).
: see http://reluk.ca/project/Breccia/Web/imager/
+ Correct the proper names of projects generally.
+ Try using `hgroup` to retitle each project readme file with both the proper name
and summary description of the project.
+ Does Git Hub Markdown allow for `hgroup`?
+ Refer to Markdown definitions from Web bookmarks.
rhetoric last, rule of
- never engage in rhetoric till after the following are accomplished
a) know two things:
⁃ of what I would inform the reader
⁃ why the reader needs that information
b) write those things plainly, with minimal rhetoric
summary description, HTML
/ For instance the opening paragraph in a project readme file, e.g.
: see http://reluk.ca/project/wayic/
: see http://reluk.ca/project/wayic/cast/
- Defer formal references (here formed as hyperlinks) to a subsequent list.
/ So after the style of Breccian afterlinkers, as in the present file.
∵ Clarity is crucial here.
∵ Clarity would suffer in the presence of formal references.
∵ References tend to be thick here.
∵ Here terms are introduced.
∵ Formed as hyperlinks, references are a distraction to the reader.
term reference, formal
: see also `^*implicit$` @ `^*referencing$` @ ~/work/Breccia/Web/imager/notes.brec
- Avoid formal references to indexed term definitions.
/ The purpose is to avoid overburdening authors with writing cross references.
- Expect readers by their own initiative to refer to local `glossary.brec` files
or the general index.
: re `general index` see http://reluk.ca/project/way/index.brec
: re `by their own initiative` cf. `^*implicit$` @ `^*referencing$` @
~/work/Breccia/Web/imager/notes.brec
∴ Tell the location of the general index in each `glossary.brec` file, at the least.
- Make an exception to this rule wherever the reader should be assumed naive, as in the summary
description of a project (readme files), or a basic instructional text.
\ Copyright © 2019-2023 Michael Allan.