Skip to content

Commit

Permalink
Expand "style" advice, make own section
Browse files Browse the repository at this point in the history
Create a new "Source Presentation" section under "Contributing", which
expands slightly on the advice for how to properly "style" raw markup.
In particular, add a reference to sembr.org, which is a semi-formalized
presentation of similar guidelines. (I actually believe I came up with
the system I use independently, but it has rather obvious benefits for
version controlled prose, and being able to point out that other people
are using similar systems is always beneficial.)

Closes #87.
  • Loading branch information
mwoehlke committed Nov 21, 2024
1 parent 05e6ee7 commit 174e53c
Showing 1 changed file with 16 additions and 2 deletions.
18 changes: 16 additions & 2 deletions development.rst
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,9 @@ that has not been previously discussed,
it is likely that you will be asked to make changes
before your proposal is accepted.

Source Presentation
^^^^^^^^^^^^^^^^^^^

When editing the documentation,
please keep in mind that whitespace,
and line breaks in particular,
Expand All @@ -50,14 +53,23 @@ in a way that aims to reduce diff churn
if and when the text is subsequently revised.
Therefore, do not try to use all available space
or slavishly wrap at a particular column.
Rather, keep lines shorter
and try to break at "natural" boundaries,
Rather, keep lines shorter,
try to break at "natural" boundaries,
and **always** break after a sentence.
As a semi-hard limit, reST text
should avoid exceeding 79 characters on a line;
however, "properly" broken lines
should rarely approach that limit.

Consider also `Semantic Line Breaks`_ for more details.
While those guidelines are not precisely followed here,
there is significant overlap, especially in rationale.
(Here, we tend to add or omit breaks
in a way that keeps line length
somewhat consistent within a paragraph.
However, the placement of breaks
should still *roughly* follow SLB guidance.)

Commits
^^^^^^^

Expand Down Expand Up @@ -94,4 +106,6 @@ with as little noise and clutter as possible.

.. _mailing list: https://groups.google.com/g/cxx-ecosystem-evolution/about

.. _Semantic Line Breaks: https://sembr.org/

.. kate: hl reStructuredText

0 comments on commit 174e53c

Please sign in to comment.