Re: Updated maint-guide contents, question on style
Osamu Aoki wrote:
> Method 1 : 14
> long-explanation-text (see ...).
> Maybe OK.
Usually OK. However, if long-explanation-text is ever long enough to
result in it being divided up into multiple sentences, it becomes less
natural to have the final reference attached to whichever sentence
happens to be final.
> Method 2 : 0
> long-explanation-text (See … .)
> Is the period after … located in parentheses or should be outside of
> them?
If long-explanation-text ends with a period/question mark/exclamation
mark then this is the preferred way to add parenthetical material - as
a full sentence with its own punctuation inside the parentheses.
> Method 3 : 13
> long-explanation-text. See ... .
> Maybe OK.
>
> Method 4 : 4
> long-explanation-text, see ... .
> Not right. This joints 2 full sentences without "and".
>
> Method 5 : 0
> long-explanation-text; see ... .
> Is this right fix for Method 4?
A strange and arbitrary rule when you think about it, but yes:
"comma splices" are bad, "semicolon splices" are perfectly OK.
Promoting it all the way to method 3 is also OK.
In general, parenthesised approaches present the reference as
"optional extra" commentary on the text, while the unparenthesised
approaches make the reference into an integral part of the text.
> Method 6 <footnote>See ... .: 17
> long-explanation-text. <footnote>See ... .</footnote>
> Good. (But address different needs)
> This has reason to make them go at the bottom of page.
You wouldn't want to do this for each item of a long list, but it's
appropriate if there's a lot of information in the footnote, or if
fitting it into the text at that point would make it hard to follow.
> I want to hear how to fix them.
A further complication is that different rules may need to be applied
in the case of a *short* explanation text. In that context it's more
normal for each list item to be a (parallel) phrase or clause, forming
a single sentence that may run from the introductory text, through
(usually) a colon, and on through to the end of the list. In that
case, you don't want to break it by making the "see foo" into a
separate sentence, and keeping the references in parentheses helps to
stop them interfering with the flow of the sentence.
If *every* list item has an associated reference, this regular
structure makes it tempting to moves it towards a tabular format, and
the next step in that direction is a definition list:
headword (see reference):
long-explanation-text
e.g. <example>
headword (see reference):
long-explanation-text
e.g. <example>
headword (see reference):
long-explanation-text
e.g. <example>
But this is usually the point at which markup schemes start making
things difficult.
> Also, if you have time, can you read the English source and propose
> fixes.
Certainly.
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
Reply to: