Editorial guidelines for 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 : see @ http://reluk.ca/project/building/Makeshift/notepad.brec - A project may assume that the reader is running Linux, provided it refers to this note. - 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. 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 associative references, 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 `^^reference, implicit$` @ ~/work/Breccia/Web/imager/notepad.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 `lexicon.brec` files or the general index. : re `^^general index$` see http://reluk.ca/project/wayic/refractory/index.brec : re `by their own initiative` cf. `^^reference, implicit$` @ ~/work/Breccia/Web/imager/notepad.brec Tell the location of the general index in each `lexicon.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-2022 Michael Allan. Licence MIT.