Updated maint-guide contents, question on style
Hi,
I have updated maint-guide. In squeeze, I knew some contents were not
very good English, we did not make invasive changes to avoid breaking PO
translation and to have readable translations.
Now we have released squeeze, it is high time to make invasive changes.
I made some major restructurings.
* Move to the DocBook XML source
* Use of more itemized list
(easy add/remove of items without breaking translation.)
* Addition of pointers to the non-technical information.
Homepage: http://www.debian.org/doc/devel-manuals#maint-guide
Vcs-Svn: svn://svn.debian.org/svn/ddp/manuals/trunk/maint-guide
Vcs-Browser: http://svn.debian.org/viewsvn/ddp/manuals/trunk/maint-guide/
As I read/translated it, I saw many inconsistencies which need to be
fixed. One of them is the referral to the externalr resource. For example:
http://www.debian.org/doc/manuals/maint-guide/start.en.html#debiandeveloper
this section has many referrals.
Here are the situation I am wondering. (# are occurrences)
Method 0: 19
long-explanation-text. (see <ulink url="..."/>)
long-explanation-text. (see <ulink url="..."/>).
These are bad. But how should I fix.
Method 1 : 14
long-explanation-text (see ...).
Maybe OK.
Method 2 : 0
long-explanation-text (See … .)
Is the period after … located in parentheses or should be outside of
them?
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?
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.
I want to hear how to fix them.
Also, if you have time, can you read the English source and propose
fixes.
Osamu
PS: maint-guide was written by non-native English speakers.
Reply to: