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/building/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.