[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Updated maint-guide contents, question on style


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:
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

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


PS: maint-guide was written by non-native English speakers.  

Reply to: