Editorial guidelines

    - 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> <target>…
            - 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
        : see @ http://reluk.ca/project/building/Makeshift/action_plan.brec
        - Presently the description of a project may assume the reader is running Linux,
          e.g. in its examples and other illustrations, on condition it refers to this note.
        - Readers should adjust the file paths and so forth to match their own systems, to the best
          of their ability.
        - This seems a safe assumption from a development perspective.
            ∵ The target readership at this early stage is technically skilled and thereby well able
              to make the necessary adjustments and continue reading.

    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/wayic/Web/imager/action_plan.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/wayic/Web/imager/action_plan.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-2021  Michael Allan.  Licence MIT.