Chapter 10 ¤å¥óªº¼¶¼g­·®æ

Table of Contents
10.1 Style guide
10.2 µü·Jªí

¥Ñ©ó FreeBSD ¤å¥ó¬O¥Ñ²³¦h§@ªÌ©ÒºûÅ@ªº¡A¬°¤F«O«ù¼g§@­·®æªº¤@³e©Ê¡A ©ó¬O´N²£¥Í¸û¦³¦@ÃѪº¼g§@³W«h¡A½Ð¦U¦ì°O±o­n¿í¦u¡C

¨Ï¥Î¬ü¦¡­^»y

¦P¤@­Ó¦r¦b¤£¦PºØÃþªº­^»y·|¦³µÛ¤£¦Pªº«÷ªk¡C ¹J¨ì«÷¦r¤£¦Pªº±¡ªp¡A½Ð±Ä¥Î¬ü¦¡­^»y«÷ªk¡C ¹³¬O¡G ½Ð§ï¥Î ¡§color¡¨¡A¦Ó«D ¡§colour¡¨¡C ½Ð§ï¥Î ¡§rationalize¡¨¡A¦Ó«D ¡§rationalise¡¨ µ¥µ¥Ãþ¦ü¦r·J¡C

Note: ­Y¤å³¹±Ä¥Î­^¦¡­^»y¤]¥i¥H±µ¨ü¡A¦ý¥²¶·¥þ½g¤å³¹³£±Ä¥Î¦P¤@«÷ªk¤~¦æ ¡C ¦Ó¤å¥óªº¨ä¥L³¡¥÷¡A¹³¬O®Ñ¡Bºô­¶¡B manual »¡©úµ¥«h¥²¶·±Ä¥Î¬ü¦¡­^»y¡C

¤£­n¥Î²¼g

½Ð¤£­n²¼g(contraction)¡C ½Ð°È¥²±N§¹¾ãªº¦r¼g¥X¨Ó¡C ¤ñ¦p¡G ¡§Don't use contractions¡¨ ³o¥y¦³¥Î¨ì²¼g¡A´N­nÁ×§K¡C

¥¿¦¡®Ñ­±¼gªkÁ×§K²¼gªº­ì¦]¡A¤D¬O¦]¬°¦p¦¹¤@¨Ó¦r¥y·N«ä¸ûºë·Ç¡A ¥B¹ïĶªÌ·|¤ñ¸û»´ÃP¨Ç¡C

¥¿½T¨Ï¥Î serial comma ¥H¤Î¹y¸¹

­^¤å¬q¸¨³q±`·|³r¸¹(,)§@¬°¸Ó¥y©Ò´£¨ìªº¦U¶µ¥Øªº»y®ð°Ï¹j¡C ¨Ã¥B·|¦b³Ì«á¤@­Ó´£¨ìªº¶µ¥Ø®É¡A¥ý¥[¤W³r¸¹¦A±µ¤W ¡§and¡¨¡A ³Ì«á¤~¬O³Ì«áªº¶µ¥Ø¡C

Á|­Ó¨Ò¤l¡A¬Ý¬Ý¤U­±³o¥y¡G

This is a list of one, two and three items.

¨º»ò³o¤@¥y¨ì©³¬O¦³¤T­Ó¶µ¥Ø(¡§one¡¨¡B¡§two¡¨ ¡B¡§three¡¨)©O¡H©ÎªÌ¬O¥u¦³¨â­Ó¶µ¥Ø(¡§one¡¨¡B ¡§two and three¡¨)©O¡H

¦]¦¹¸û§´ªº¤è¦¡¬O¥H serial comma ªº¤è¦¡¡A¤~¯à¥¿½Tªí¹F»y·N¡G

This is a list of one, two, and three items.

µM¦Ó¡A¦b½Ķ¹Lµ{¤¤¡A«ØÄ³§â³r¸¹(,)³¡¥÷§ï¬°¹y¸¹(¡B)¡A¨Ã¥B ¡§and¡¨ ªº³¡¥÷¥i²¤¦Ó¤£Â½¡A¥H§K»y·N¹y¶ë¡C

Á×§K¨Ï¥ÎÂØµü

½Ð¸ÕµÛÁ×§K¨Ï¥ÎÂØµü(redundant phrase)¡C ¤×¨ä¬O ¡§³o­Ó«ü¥O¡¨¡B¡§³o­ÓÀɮס¨¡B¡§man «ü¥O¡¨ ³o´X­Ó³q±`³£¬O¤£¥²­nªºÂصü¡C

¥H«ü¥O(command)¤è­±Á|¨Ò¡A¤ñ¸û§´·íªº¥Îªk¬O²Ä¤G¥yªº¨Ò¤l¡G

¨Ï¥Î cvsup «ü¥O¨Ó§ó·s­ì©l½X¡C

¨Ï¥Î cvsup ¨Ó§ó·s­ì©l½X¡C

¥HÀÉ®×(filename)¤è­±Á|¨Ò¡A¤ñ¸û§´·íªº¥Îªk¬O²Ä¤G¥yªº¨Ò¤l¡G

... ¦b³o­Ó /etc/rc.local ÀÉ®× ...

... ¦b /etc/rc.local ÀÉ ...

¥H man(manual)¤è­±Á|¨Ò¡A¤ñ¸û§´·íªº¥Îªk¬O²Ä¤G¥y(¦³¥Î¨ì SGML <citerefentry> ¼ÐÅÒ)¡G

½Ð¥´ man csh «ü¥O¥H°Ñ¾\¸Ô±¡»¡©ú¡C

¸Ô±¡½Ð°Ñ¾\ csh(1)¡C

¨C¥y«á­±¥[¤W¨â­ÓªÅ¥Õ

¬°¤F¨Ï¤å³¹§ó©ö¾\Ū¡A¥H¤ÎÅý Emacs ¤§Ãþªº¤u¨ã®e©ö¹B¥Î¡A½Ð¦b¨C¤@§¹¾ã¥y¤l«á­±¥[¤W¨â­ÓªÅ¥Õ¡C

¤£¹L¡A¥y¸¹(.)«á­±¦³±µ¤j¼g¦r¥À¡A ¨Ã¤£¤@©wªí¥Ü«e¤@­Ó¥yÂI©Ò¦b³B´N¬O§¹¾ã¥y¤l¡A ¤×¨ä¬O¦W¦r³¡¥÷±`±`·|¦³³o²{¶H¡C ¹³¬O ¡§Jordan K. Hubbard¡¨ ³o¤H¦W´N¬O«Ü¦nªº¨ÒÃÒ¡G¥y¸¹«á­±±µªÅ¥Õ¡AµM«á¬O¤j¼gªº H¡AµM¦Ó³oªÖ©w¨Ã¤£¬O¨â¬q¥y¤l¡C

¼¶¼g­·®æªº¬ÛÃö²Ó¸`¡A¥i°Ñ¾\ William Strunk ©Ò¼gªº Elements of Style¡C

10.1 Style guide

¥Ñ©ó Handbook ¬O¥Ñ²³¦h§@ªÌ©ÒºûÅ@¡A¬°¤F«O«ù¼g§@­·®æªº¤@³e©Ê¡A ½Ð¿í¦u¤U¦C¼¶¼g­·®æ¡C

10.1.1 ¤j¤p¼g

Tag ªº³¡¥÷³£¬O¥Î¤p¼g¦r¥À¡AÄ´¦p¬O¥Î <para> ¡A¦Ó«D <PARA>¡C

¦Ó SGML ¤º¤å«h¬O¥Î¤j¼g¦r¥Àªí¥Ü¡A¹³¬O¡G <!ENTITY...> ¤Î <!DOCTYPE...>¡A ¦Ó¤£¬O <!entity...> ¤Î <!doctype...>¡C

10.1.2 ÁY¼g¦r

ÁY¼g¦r(acronym)³q±`¦b®Ñ¤¤²Ä¤@¦¸´£¨ì®É¡A¥²¶·¦P®É¦C¥X§¹¾ã«÷ªk¡A ¤ñ¦p¡G"Network Time Protocol (NTP)"¡C ©w¸qÁY¼g¦r¤§«á¡AÀ³¸Ó¾¨¶q¥u¨Ï¥Î¸ÓÁY¼g¦r(¦Ó«D§¹¾ãµü·J¡A °£«D¨Ï¥Î§¹¾ãµü·J¥i¥H§ó¯àªí¹F»y·N)¨Óªí¹F§Y¥i¡C ³q±`¨C¥»®Ñ¥u·|²Ä¤@¦¸´£¨ì®É¡A¤~·|¦C¥X§¹¾ãµü·J¡A ¦ý­Y±z°ª¿³¤]¥i¥H¦b¨C³¹²Ä¤@¦¸´£¨ì®É¤S¦C¥X§¹¾ãµü·J¡C

¦¹¥~¡A¦P¤@ÁY¼g¦r¦b«e¤T¦¸¨Ï¥Î®É¡A¶·¨Ï¥Î <acronym> ¼ÐÅÒ¡A ¨Ã§â§¹¾ãµü·Jªþ¦b role Äݩʤº°µ»¡©ú¡C ¦p¦¹¤@¨Ó´N·|«Ø¥ßµü·Jªí¡A¨Ã¥B·í·Æ¹«²¾¦Ü¸ÓÁY¼g¦r¤W¤è®É¡A ´N·|Åã¥Ü§¹¾ãµü·J¡C

10.1.3 ÁY±Æ

µL½× ÀÉ®×ÁY±Æ³]©w¬°¦ó¡A ¨C­ÓÀɮפ@¶}©lªºÁY±Æ(indentation)³£¬O±q 0 Áa¦C¶}©l

¥¼§¹ªº¼ÐÅÒ·|¥H¦h¨â­ÓªÅ¥Õ¨Ó¼W¥[ÁY±Æ¡A µ²§Àªº¼ÐÅÒ«h¤Ö¨â­ÓªÅ¥Õ¨ÓÁY´îÁY±Æ¡C ­Y¤w¹F 8 ­ÓªÅ¥Õ¡A«h¥H tab ¨ú¥N¤§¡C ¦¹¥~¡A¦b tab «e­±¤£­n¦A¥ÎªÅ¥Õ¡A¤]¤£­n¦b¨C¦æ«á­±¥[¤WªÅ¥Õ¡C ¨C­Ó tag ªº¤º¤å­Y¶W¹L¤@¦æªº¸Ü¡A«h±µ¤U¨Óªº´N¦h¨â­ÓªÅ¥Õ¥H°µÁY±Æ¡C

Á|­Ó¨Ò¤l¡A³o¸`©Ò¥Îªº¼gªk¤j­P¬O¤U­±³o¼Ë¡G

+--- ³o¬O 0 Áa¦C
V
<chapter>
  <title>...</title>

  <sect1>
    <title>...</title>

    <sect2>
      <title>ÁY±Æ</title>

      <para><emphasis>µL½×</emphasis> ÀÉ®×ÁY±Æ³]©w¬°¦ó¡A
        ¨C­ÓÀɮפ@¶}©lªºÁY±Æ(indentation)³£¬O±q 0 Áa¦C¶}©l¡C</para>

      ...	
    </sect2>
  </sect1>
</chapter>

­Y¥Î Emacs ©Î XEmacs ¨Ó½s¿è³oÀÉ¡A¨º»ò·|¦Û°Ê¶i¤J sgml-mode ¼Ò¦¡¡A µM«á´N·|±j¨î¨Ï¥Î¨C­ÓÀɮ׳̤U¤èªºÀô¹Ò³]©w¡C

Vim ·R¥ÎªÌ¤]¥i¥H¥Î¤U¦C³]©w¨Ó½Õ¾ã¡G

augroup sgmledit
  autocmd FileType sgml set formatoptions=cq2l " ¯S®í®æ¦¡¿ï¶µ
  autocmd FileType sgml set textwidth=70       " ¦b 70 Áa¦C³B§Y¦Û°Ê´«¦æ
  autocmd FileType sgml set shiftwidth=2       " ¦Û°ÊÁY±Æ 2 ­ÓªÅ¥Õ
  autocmd FileType sgml set softtabstop=2      " «ö Tab ·|¦Û°ÊÂର¨â­ÓªÅ¥ÕÁY±Æ
  autocmd FileType sgml set tabstop=8          " §â 8 ­ÓªÅ¥ÕÂର tab
  autocmd FileType sgml set autoindent         " ¦Û°ÊÁY±Æ
augroup END

10.1.4 Tag ­·®æ

10.1.4.1 Tag ªÅ¦æ

¦P¤@ÁY±Æµ¥¯Åªº¼ÐÅÒ­n¥HªÅ¤@¦æ¨Ó°µ°Ï¹j¡A¦Ó¤£¦PÁY±Æµ¥¯Åªº«h¤£¥²¡C ¤ñ¦p¡G

<article>
  <articleinfo>
    <title>NIS</title>

    <pubdate>October 1999</pubdate>

    <abstract>
      <para>...
	...
	...</para>
    </abstract>
  </articleinfo>

  <sect1>
    <title>...</title>

    <para>...</para>
  </sect1>

  <sect1>
    <title>...</title>

    <para>...</para>
  </sect1>
</article>

10.1.4.2 ¼ÐÅÒªº¤À¦æ

¹³¬O <itemizedlist> ³oÃþªº¼ÐÅҨƹê¤W¥»¨­¤£§t¥ô¦ó¤å¦r¸ê®Æ¡A¥²¶·±o¥Ñ¨ä¥L¼ÐÅҨӸɥR¤º¤å¡C ³oÃþªº¼ÐÅÒ·|¿W¥Î¤@¾ã¦æ¡C

¥t¥~¡A¹³¬O <para> ¤Î <term> ³oÃþªº¼ÐÅҨ䣻ݷf°t¨ä¥L¼ÐÅÒ¡A ´N¥iªþ¤W¤å¦r¸ê®Æ¡A¨Ã¥B¦b¼ÐÅÒ«á­±ªº¦P¤@¦æ ¤º§Y¥i¥ß§Y¼g¤W³o¨Ç¤º¤å¡C

·íµM¡A³o¨âÃþªº¼ÐÅÒµ²§À®É¤]¬O¸ò¤W­±¹D²z¬Û¦P¡C

¤£¹L¡A·í¤W­z³o¨âºØ¼ÐÅÒ²V¥Î®É¡A·|¦³«Ü©úÅ㪺§xÂZ¡C

·í²Ä¤@Ãþ¼ÐÅÒªº«á­±±µ¤W²Ä¤GÃþ¼ÐÅÒªº¸Ü¡A ¨º»ò­n§â³o¨âÃþ¼ÐÅÒ¦U¦Û¤À¦æ¨Ó¼g¡C «áªÌ¼ÐÅÒªº¬q¸¨¡A ¤]¬O»Ý­n°µ¾A·íÁY±Æ½Õ¾ã¡C

¦Ó²Ä¤GÃþ¼ÐÅÒµ²§À®É¡A¥i¥H»P²Ä¤@Ãþ¼ÐÅÒªºµ²§À©ñ¦b¦P¤@¦æ¡C

10.1.5 ªÅ¥Õªº§ó§ï

¦b commit ­×§ï®É¡A½Ð§O¦b­×§ï¤º®eªº¦P®É¡A ¤]¤@°_§ó§ï½s±Æ®æ¦¡¡C

¦p¦¹¤@¨Ó¡A¹³¬O Handbook ½Ķ¹Î¶¤¤~¯à¨³³t§ä¥X§A§ï¤F­þ¨Ç¤º®e¡A ¦Ó¤£¥Î¶O¤ß«ä¥h§PÂ_¸Ó¦æªº§ïÅÜ¡A¬O¥Ñ©ó®æ¦¡­«±Æ©ÎªÌ¤º®e²§°Ê¡C

Á|¨Ò»¡©ú¡A­Y­n¦b¬Y¬q¥[¤W¨â­Ó¥y¤l¡A¦p¦¹¤@¨Ó¸Ó¬q¸¨ªº¬Y¦æ¶Õ¥²·|¶W¥X 80 Áa¦C¡A³o®É½Ð¥ý commmit ­×§ï¡C ±µµÛ¡A¦A­×¹¢¹Lªø¦æ¸¨ªº´«¦æ¡AµM«á¦A¦¸ commit ¤§¡C ¦Ó²Ä¤G¦¸ªº commit ¬ö¿ý¡A½Ð©ú½T»¡©ú³o¥u¬O whitespace-only (­×§ïªÅ¥Õ¦Ó¤w) ªº§ó§ï¡A¦p¦¹¤@¨Ó¡A½Ķ¹Î¶¤´N¥i¥H©¿²¤²Ä¤G¦¸ commit ¤F ¡C

10.1.6 Nonbreaking space

½ÐÁ×§K¤@¨Ç±¡ªp¤UªºÂ_¦æ¡G³y¦¨ª©­±ÁàÁ઺¡B©Î¬O¶·³s³eªí¹Fªº¦P¤@¥y¤l¡C Â_¦æªº±¡ªp·|ÀH©Ò¾\Ūªº¤u¨ã¤£¦P¦Ó¦³©Ò¤£¦P¡C ¤×¨ä¬O³z¹L¯Â¤å¦rÂsÄý¾¹¨Ó¬Ý HTML ®É·|§ó©úÅã¬Ý¨ìÃþ¦ü¤U­±³o¼Ë¤£¦nªº½s±Æ¬q¸¨¡G

Data capacity ranges from 40 MB to 15
GB.  Hardware compression ...

½Ð¨Ï¥Î &nbsp; ¥HÁ×§K¦P¥y¤l¤§¶¡ªºÂ_¦æ¡A ¥H¤U¥Ü½d¦p¦ó¨Ï¥Î nonbreaking spaces¡G

  • ¦b¼Æ¦r»P³æ¦ì¤§¶¡¡G

    57600&nbsp;bps
    
  • ¦bµ{¦¡¦WºÙ»Pª©¸¹¤§¶¡¡G

    FreeBSD&nbsp;4.7
    
  • multiword ¤§¶¡ (¨Ï¥Î®É½Ð¤p¤ß¡A¹³¬O ¡§The FreeBSD Brazilian Portuguese Documentation Project¡¨ ³oÃþ¥Ñ¤T¨ì¥|­Ó¦r©Ò²Õ¦¨ªº¡A «h¤£¥Î¥[¡C)¡G

    Sun&nbsp;Microsystems
    

¥»¤å¤Î¨ä¥L¤å¥ó¡A¥i¥Ñ¦¹¤U¸ü¡Gftp://ftp.FreeBSD.org/pub/FreeBSD/doc/¡C

­Y¦³ FreeBSD ¤è­±ºÃ°Ý¡A½Ð¥ý¾\Ū FreeBSD ¬ÛÃö¤å¥ó¡A¦p¤£¯à¸Ñ¨Mªº¸Ü¡A¦A¬¢¸ß <questions@FreeBSD.org>¡C
Ãö©ó¥»¤å¥óªº°ÝÃD¡A½Ð¬¢¸ß <doc@FreeBSD.org>¡C