Reason: None X-Bugzilla-Product: Documentation X-Bugzilla-Component: Books & Articles X-Bugzilla-Version: Latest X-Bugzilla-Keywords: X-Bugzilla-Severity: Affects Only Me X-Bugzilla-Who: bigsneaky@duck.com X-Bugzilla-Status: New X-Bugzilla-Resolution: X-Bugzilla-Priority: --- X-Bugzilla-Assigned-To: doc@FreeBSD.org X-Bugzilla-Flags: X-Bugzilla-Changed-Fields: bug_id short_desc product version rep_platform op_sys bug_status bug_severity priority component assigned_to reporter Message-ID: Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="UTF-8" X-Bugzilla-URL: https://bugs.freebsd.org/bugzilla/ Auto-Submitted: auto-generated List-Id: Documentation project List-Archive: https://lists.freebsd.org/archives/freebsd-doc List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-freebsd-doc@FreeBSD.org MIME-Version: 1.0 https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=3D291216 Bug ID: 291216 Summary: fdp-primer style guide unclear if "one sentence per line" should be split over multiple lines Product: Documentation Version: Latest Hardware: Any OS: Any Status: New Severity: Affects Only Me Priority: --- Component: Books & Articles Assignee: doc@FreeBSD.org Reporter: bigsneaky@duck.com The FreeBSD Documentation Project Primer has a "One sentence per line" sect= ion in the "Writing Style" chapter: https://github.com/freebsd/freebsd-doc/blob/main/documentation/content/en/b= ooks/fdp-primer/writing-style/_index.adoc > Use Semantic Line Breaks in the documentation, a technique > called "one sentence per line". > The idea of this technique is to help the users to write and > read documentation. > To get more information about this technique read the > link:https://sembr.org/[Semantic Line Breaks] page. The capitalization of "Semantic Line Break" and link to https://sembr.org suggest "one sentence per line" is being treated as synonymous with the "Semantic Line Breaks Specification (SemBr)" proposed there. Starting each sentence on a new line (the only instruction explicitly documented in the FDP Primer) is clearly a form of semantic line break, but SemBr goes further: it suggests splitting sentences over multiple lines for various reasons, such as: > A semantic line break SHOULD occur after an independent clause > as punctuated by a comma (,), semicolon (;), colon (:), or em dash (=E2= =80=94). > A semantic line break MAY be used after one or more items in a list in > order to logically group related items or satisfy line length constraints. > A maximum line length of 80 characters is RECOMMENDED. The FDP Primer and SemBr both use a paragraph from the UDHR as an example. = The former recommends splitting into two lines (one for each sentence), the lat= ter into three lines (splitting one sentence into two clauses). The FDP Primer = does not mention the possibility of splitting sentences between clauses or list items, nor does it recommend a maximum line length. Overall it is unclear whether it is instructing: 1. To simply write each sentence on its own line, like in its UNDR example. 2. To start each sentence on a new line but optionally consider further line breaks within sentences where semantically appropriate. 3. To follow the linked SemBr specification, which is more prescriptive (e.= g. 80 characters line length). If (2) or (3), the Primer needs some guidance on where additional line brea= ks are recommended, and the UNDR example needs tweaking. If (1) or (2), "Seman= tic Line Breaks" should be decapitalized and, if linked, the status of SemBr sh= ould be clarified: it's also a form of semantic line breaking, but how is it different from "one sentence per line", and how closely should its prescriptions be followed in FreeBSD docs? Or could an alternative link tar= get be found - SemBr itself links to a 2012 post by Brandon Rhodes: https://rhodesmill.org/brandon/2012/one-sentence-per-line This explains the motivation, gives a historical overview back to Brian W. Kernighan, and is less prescriptive than SemBr - hopefully less likely to confuse the reader with conflicting rules. Just note that some of its examp= les use semantic line breaks even more aggressively than SemBr, e.g. to separate dependent clauses. I don't know how this (or SemBr) compares to norms across the FreeBSD docs tree. --=20 You are receiving this mail because: You are the assignee for the bug.=