:::

CSSDOC標籤參考表

10月 12, 2010 0 Comments Edit Copy Download

image

繼上一篇介紹CSSDOC之後,這一篇則是更詳細地將CSSDOC推薦的32種標籤(tag)做一個翻譯整理。原本CSSDOC的標籤只有寫在草案的PDF中(SkyDrive備份),查詢起來不是很方便,所以我想寫一個方便自己查閱的網頁版。

原文草案中標籤的編排是以英文字母順序排列,但是這在使用上並不方便,我用個人的看法重新為他排列,並分成檔案註解標籤、區段註解標籤、參考資訊標籤、檢測標籤、錯誤修正與迴避標籤、其他標籤六類。希望這種編排能夠更容易使用CSSDOC的標籤。

標籤內會用到原文草案的附錄與內文,我將比較複雜的標籤值與瀏覽器翻譯整理之後附在文後的附錄中,供大家方便查閱。

凡例

標題

為了方便索引與使用,標題的格式將會包含「標籤名稱」、「簡稱」與「用法」等三種資訊。以下是其中一個例子:

@affected 影響瀏覽器:用於錯誤修正(bugfix)或隱藏錯誤(workaround)時指定目標瀏覽器與版本。
  • 標籤名稱@affected
  • 簡稱:影響瀏覽器
  • 用法:用於錯誤修正(bugfix)或隱藏錯誤(workaround)時指定目標瀏覽器與版本。

標籤敘述

標籤敘述是以標籤名稱、位置、狀態、用法、標籤值、備註、參見、範例所組成。

  • 標籤名稱:以「@」開頭與英文組合成的名稱,後面接著是我個人對他的簡稱。
  • 位置:此標籤可以使用的位置,包含檔案註解(File Comment)、區段註解(Section Comment)與標準CSS註解(Standard CSS Comment)三種。
  • 狀態:此標籤在CSSDOC中的制訂現況,可能是不穩定、即將被捨棄,或是有一些特殊的用法。
  • 用法:此標籤的適用情況與使用方法。
  • 標籤值:應該接續在此標籤後面的資料。部分標籤值有規範格式,請參見底下的附錄:標籤值列表。
  • 參見:與此標籤相關連的其他標籤。
  • 範例:此標籤的用法舉例。

標籤分類

我將CSSDOC分成六類,這並非CSSDOC制訂的類別,只是我覺得這樣方便自己查閱的分類法而已。這六類為:

  • 檔案標註標籤:有些標籤是描述整個檔案的資訊,在其他文件工具也很常見,例如「@author」(作者)、「@copyright」(版權聲明);
  • 區段標註標籤:有些是CSSDOC用來規範檔案架構的區段標籤,例如「@section」(區段名稱)、「@subsection」(子區段名稱);
  • 參考資訊標籤:有些是註明參考資訊的標籤,例如「@see」(參見)、「@since」(參見版本);
  • 檢測標籤:有些是標示檢測狀況的標籤,例如「@tested」(通過測試)、「@valid」(有效);
  • 錯誤修正、迴避標籤:有些是CSS語法特有的相容性、錯誤修正、替代方案說明,例如「@bugfix」(錯誤修正)、「@css-for」(這段CSS語法是為了目標瀏覽器而寫);
  • 其他標籤:有些是為了CSSDOC分析器而設計,例如「@cssdoc」(CSSDOC版本、分析器控制)。

檔案註解標籤

@author 作者:顯示作者的名字。
標籤名稱 @author 作者
位置 檔案註解
用法 顯示作者的名字。
標籤值 標明這個CSS檔案的作者。通常會附上email電子郵件位址。在多作者的情況則使用多個@author標籤,一個標籤註明一個作者。
備註 為了防止廣告機器人(spambot)分析CSS檔案找尋電子郵件地址,在公開CSS檔案的時候要考慮移除作者的電子郵件地址。
範例
/**
 * 我的CSS檔案
 *
 * @author  Mina Margin <mm@example.com>
 * @version 1
 */
@creator CSS建立工具:生產應用程式或工具可以利用此標籤留下記錄。
標籤名稱 @creator 建立工具
位置 檔案註解
用法 CSS生產應用程式或工具可以利用此標籤留下記錄。
標籤值 應用程式或工具的名稱
參見 @author
範例
/**
 * [...]
 * @creator  HTML Plus 2 Reflexive CSS (WIN 3.1)
 * [...]
 */
@copyright  檔案的版權資訊。
標籤名稱 @copyright 版權資訊
位置 檔案註解
用法 檔案的版權資訊。
標籤值 版權字串。
範例
/**
 * [...]
 * @copyright Copyright(c) 1992, 2006-2007
 *            by My Little Big Corp Inc.
 * [...]
 */
@licence 授權條款:指定CSS檔案發佈時遵守的授權條款。
標籤名稱 @license 授權條款
位置 檔案註解
用法 指定CSS檔案發佈時遵守的授權條款。
標籤值 為了確保該授權條款可辨識,通常是包含人類可以閱讀的敘述以及URL網址。
範例
/**
 * [...]
 * @license Create Commons Attribution 2.0 License
 *          http://creativecommons.org/licenses/by2.0/
 * [...]
 */
@link 參考連結:檔案參考來源的超連結。
標籤名稱 @link 參考連結
位置 檔案註解
用法 檔案參考來源的超連結。例如:如果這是某個主題的一部分,那麼可以填入該主題的網站網址。
標籤值 為了確保該授權條款可辨識,通常是包含人類可以閱讀的敘述以及URL網址。
範例
/**
 * [...]
 * @license Create Commons Attribution 2.0 License
 *          http://creativecommons.org/licenses/by/2.0/
 * [...]
 */
@date 建立日期:註明文件建立日期。
標籤名稱 @date 建立日期
位置 檔案註解
用法 註明文件建立日期。
標籤值 日期(標籤值)
參見 CSSDOC文件中的2.3.6 Parser and Control Tags章節
範例1
/**
 * [...]
 * @cssdoc version 1.0-pre
 * [...]
 */
範例2
/* @cssdoc parsing off */

[...]

/* @cssdoc parsing on */
@lastmodified 最後修改:註明最後修改的時間。
標籤名稱 @lastmodified 最後修改
位置 檔案註解
用法 註明最後修改的時間。
標籤值 最後修改的時間戳記(標籤值)
參見 @date
範例
/**
 * [...]
 * @lastmodified 2007-07-24 12:34
 * [...]
 */
@package 套裝名稱:關聯一個或多個檔案到同一個套裝程式中。
標籤名稱 @package 套裝名稱
位置 檔案註解
用法 關聯一個或多個檔案到同一個套裝程式中。
標籤值 套裝程式名稱
參見 @version@subpackage
範例
/**
 * [...]
 * @package    xhtml-css
 * @subpackage css
 * [...]
 */
@subpackage 子套裝名稱:分類套裝程式用。
標籤名稱 @subpackage 子套裝名稱
位置 檔案註解
用法 分類套裝程式用。
標籤值 子套裝程式名稱
參見 @package
範例
/**
 * [...]
 * @package    xhtml-css
 * @subpackage css
 * [...]
 */
@style 樣式:這個樣式的命名,或是這個樣式檔案所屬類別。
標籤名稱 @style 樣式
位置 檔案註解
用法 這個樣式的命名,或是這個樣式檔案所屬類別。
標籤值 文字(標籤值)
參見 @project
範例
/**
 * [...]
 * @style     couleurs de l'été
 * [...]
 */
@version 版本:標示檔案版本。
標籤名稱 @version 版本
位置 檔案註解
用法 標示檔案版本。
標籤值 版本號碼
參見 @revision
範例
/**
 * [...]
 * @version   1.2
 * [...]
 */
@revision 修訂次數:註明檔案的修訂次數。
標籤名稱 @revision 修訂次數
位置 檔案註解
用法 註明檔案的修訂次數。用於SVN或類似的原始碼管理系統。
狀態 這是不穩定的標籤,也許會列入廢棄標籤。由於@version標籤已經可以相容此功能,而@revision在標準的版本控制系統中沒有用處。
標籤值 修訂次數
參見 @version
範例
/**
 * [...]
 * @version  0.2.8
 * @revision 193
 * [...]
 */
@site 網站名稱:這個CSS檔案套用的網站名稱。
標籤名稱 @site 網站名稱
位置 檔案註解
用法 這個CSS檔案套用的網站名稱。
標籤值 文字(標籤值)
參見 @project@link@package
備註 @package可能也會是選項之一。
範例
/**
 * couleurs de l'été
 *
 * MyWebsite Style for Summer 2008
 *
 * @site     mywebsite
 * [...]
 */
@media 套用載體:敘述該檔案套用的目標載體類型。
標籤名稱 @media 套用載體
位置 檔案註解
用法 敘述該檔案套用的目標載體類型。例如print、screen。詳細的
標籤值 CSS載體敘述,例如print、screen。請參考W3C的Media types說明
備註 跟CSS選取器是同樣的文字。
範例
/**
 * [...]
 * @license Create Commons Attribution 2.0 License
 *          http://creativecommons.org/licenses/by2.0/
 * [...]
 */
@colordef 定義顏色。
標籤名稱 @colordef 顏色定義
位置 檔案註解
用法 定義顏色。
標籤值 顏色定義字串包含了標準的CSS顏色值、作者自訂的顏色名稱。如果有使用的話,可以在最後用括號註明該顏色的用處。
其他資訊 @colordef標籤是讓CSS作者能夠有系統地定義使用的顏色。如果確實使用@colordef,就能利用程式或工具快速地確認顏色並且方便地變換整體色調(Palette)。
參見 @affected@css-for@workaround
範例1
/**
[...]
 *
 * @colordef #7b633a; Bronze (Border)
 * @colordef rgb(24,56,68); Dark Satin (Lter Shadow)
 * @colordef rgb(12,47,56); Darker Satin (Shadow)
 * @colordef red; Red
 */
範例2
/**
[...]
 * @colordef rgb(45,71,108);   Camou d'accord (activeBackground)
 * @colordef rgb(142,155,161); Rhyme Dump Down (activeBlend)
 * @colordef rgb(251,251,231); Sellout Gay Gray (activeForeground)
 * @colordef rgb(142,155,161); Less Red* (activeTitleBtnBg)
 * @colordef rgb(242,242,223); Snowflash (alternateBackground)
 * @colordef rgb(240,240,214); Pay for Grey (background)
 * @colordef rgb(230,230,205); Silver Snow Boots (buttonBackground)
 * @colordef rgb(0,0,0);       Black (buttonForeground)
 * @colordef rgb(0,0,0);       Black (foreground)
 * @colordef rgb(157,168,169); Tripple Sec Dry Grey (frame)
 * @colordef rgb(157,168,169); Tripple Sec Dry Grey (handle)
 * @colordef rgb(95,114,135); Minor Mist (inactiveBackground)
 * @note     glad-beige-colors
 * @see      http://www.kde-look.org/content/show.php?content=75982
 */
@forntdef 定義字型。
標籤名稱 @fontdef 字型定義
位置 檔案註解
用法 定義字型。
標籤值 字型定義(標籤值)。但是CSSDOC草案中這部份還尚未確定。
參見 @colordef
範例
/**
 * [...]
 * @fontdef freesans, arial, sans-serif, sans;
 *          serifenlose classique (headlines)
 * [...]
 */

區段註解標籤

@section 區段名稱:開啟一個新的區段並命名。
標籤名稱 @section 區段名稱
位置 區段註解
用法 開啟一個新的區段並命名。
標籤值 區段名稱
參見 @subsection@see
範例
/**
 * 重置區塊
 *
 * 重置到預設狀況。
 * 
 * @section reset
 * @see     YUI Reset CSS,
 *          http://developer.yahoo.com/yui/reset/
 */
@subsection 子區段名稱:增加CSS檔案的結構。
標籤名稱 @subsection 子區段名稱
位置 區段註解
用法 增加CSS檔案的結構。
標籤值 子區段名稱

參見 @section@subsubsection
範例
/**
 * [...]
 * @section    reset
 * [...]
 */
[...]
/**
 * [...]
 * @subsection forms
 * [...]
 */
@subsubsection 次子區段名稱:增加CSS檔案的結構。
標籤名稱 @subsection 次子區段名稱
位置 區段註解
用法 增加CSS檔案的結構。
標籤值 次子區段名稱
參見 @section@subsection
範例
/**
 * [...]
 * @subsection    forms
 * [...]
 */
[...]
/**
 * [...]
 * @subsubsection labels
 * [...]
 */

參考資訊標籤

@see 參見:檔案或區塊的參考資訊。
標籤名稱 @see 參見
位置 檔案註解、區段註解
用法 檔案或區塊的參考資訊。
標籤值 文字、URL
參見 @section@link
範例
/**
 * 重置區塊
 *
 * 重置到預設狀況。
 * 
 * @section reset
 * @see     YUI Reset CSS,
 *          http://developer.yahoo.com/yui/reset/
 */
@since 參見版本:標註參考來源或檔案的版本。
標籤名稱 @since 來原本本
位置 檔案註解、區段註解
用法 標註參考來源或檔案的版本。
標籤值 版本數字
參見 @version
範例
/**
 * 重置
 *
 * 重置到本身的預設狀態。
 * 
 * @section reset
 * @see     YUI Reset CSS,
 *          http://developer.yahoo.com/yui/reset/
 * @since   0.2.8
 */
@since-revision 參見修訂次數:標註參考來源或檔案的修訂次數。
標籤名稱 @since-revision 參見修訂次數
位置 檔案註解、區段註解
用法 標註參考來源或檔案的修訂次數。
標籤值 修訂次數
參見 @since@revision
範例
/**
 * [...]
 * @since          0.2.8
 * @since-revision 193
 */

檢測標籤

@tested 通過測試:標註該檔案或該區段已經通過測試的瀏覽器。
標籤名稱 @tested 通過測試
位置 檔案註解、區段註解
用法 標註該檔案或該區段已經通過測試的瀏覽器。
標籤值 通過測試的瀏覽器列表
備註 如果有需要排序的話,可以使用多個@tested標籤,每個標籤使用一種使用者代理(user agent)。另一個方法也可以使用逗點分隔「,」,或是同時使用。
範例
/**
 * 我的CSS隱藏錯誤測試系列
 * 
 * @workaround 邊框顯示錯誤
 * @affected   opera3-6.1 win
 * @tested     ie4, ie5, ie6, ie7
 * @tested     opera3-6.1 win
 * @tested     moz7
 */
@valid [F][S] 有效驗證:標示CSS語法是否有效。
標籤名稱 @valid 有效驗證
位置 檔案註解、區段註解
用法 標示CSS語法是否有效。
標籤值 布林值(標籤值)
備註 如果有段落或是已知錯誤修正會讓CSS語法無法生效,這就可以標示@valid標籤。注意這並不會影響分析器的開關切換。
範例
/**
 * [...]
 * @valid   false
 * [...]
 */

錯誤修正、迴避標籤

@bugfix 錯誤修正:標示這段CSS語法是一個錯誤修正。
標籤名稱 @bugfix 錯誤修正
位置 檔案註解、區段註解 、標準CSS註解
用法 標示這段CSS語法是一個錯誤修正。
標籤值 無。
備註 錯誤修正是利用CSS去修正(而非迴避)特定瀏覽器在顯示或是編譯時會出現的錯誤。
參見 @affected@css-for@workaround
範例1
/**
 * 重複文繞圖外欄(Float-Margin)的錯誤
 *
 * @see  http://...
 *
 * @bugfix
 * @affected   ie5 win, ie6
 * @css-for    all browsers
 * @valid      yes
 */
範例2
/**
 * 避免在#col3在列印時會發生換頁(page break)情況。
 *
 * @bugfix
 * @affected  ie7
 * @css-for   ie5.x win, ie6, ie7
 * @valid     yes
 */
#col3 { height: 1% }
@workaround 隱藏錯誤:標示這是一個隱藏錯誤。
標籤名稱 @workaround 隱藏錯誤
位置 檔案註解、區段註解
用法 標示這是一個隱藏錯誤。隱藏錯誤並不是錯誤修補,只是迴避錯誤發生的一個折衷方案。請看Wikipedia的解釋
標籤值 沒有資料,或是對於這個錯誤的簡單敘述。
備註 隱藏錯誤(workaround)是一種CSS用法,用來迴避(而不是修正、或甚至是無法修正)某些瀏覽器顯示或是編譯的錯誤。
參見 @bugfix
範例
/**
 * 3像素突出錯誤
 * 
 * @workaround 3像素突出錯誤
 * @affected   ie5.x, ie6
 * @css-for    ie5.x, ie6
 */
@affected 影響瀏覽器:用於錯誤修正(bugfix)或隱藏錯誤(workaround)時指定目標瀏覽器與版本。
標籤名稱 @affected 影響瀏覽器
位置 檔案註解、區段註解
用法 用於錯誤修正(bugfix)或隱藏錯誤(workaround)時指定目標瀏覽器與版本。
標籤值 瀏覽器以及版本,或是使用者代理(useragent)的群組。關於使用者代理的介紹,可以參考UserAgent的历史变迁這篇。
備註 應該只能跟@bugfix或@workaround一起使用。
參見 @bugfix@workaround附件:瀏覽器列表
範例1
/**
 * 我的CSS隱藏錯誤
 *
 * @workaround 修正錯誤的框線顯示
 * @affected   opera3-6.1 win
 */
範例2
/**
 * 避免在#col3在列印時會發生換頁(page break)情況。
 *
 * @bugfix
 * @affected  ie7
 * @css-for   ie5.x win, ie6, ie7
 * @valid     yes
 */
#col3 { height: 1% }
@css-for 套用瀏覽器:註明此段CSS語法是為了目標瀏覽器而撰寫。
標籤名稱 @css-for 套用瀏覽器

位置 檔案註解、區段註解

用法 註明此段CSS語法是為了目標瀏覽器而撰寫。

標籤值 要修正的瀏覽器名稱。

參見 @bugfix@workaround附錄:瀏覽器列表

範例
/**
 * [...]
 * @css-for IE 6 Win32.
 * [...]
 */

其他標籤

@cssdoc 控制與告知CSSDOC分析器。
標籤名稱 @cssdoc

位置 檔案註解、區段註解

用法 控制與告知CSSDOC分析器。

標籤值 CSSDOC指令(標籤值)

參見 CSSDOC文件中的2.3.6 Parser and Control Tags章節

範例1
/**
 * [...]
 * @cssdoc version 1.0-pre
 * [...]
 */
範例2
/* @cssdoc parsing off */

[...]

/* @cssdoc parsing on */
@note 筆記
標籤名稱 @note 筆記
位置 檔案註解、區段註解
用法 留下筆記。
標籤值 文字(標籤值)
參見 @todo
範例
/**
 * [...]
 * @note this is not for production use.
 * [...]
 */
@todo 待辦事項:建立待辦事項列表。
標籤名稱 @todo 待辦事項
位置 檔案註解、區段註解
用法 建立待辦事項列表。
標籤值 文字(標籤值)
備註 有些軟體可以利用todo標籤以及標籤值來建立檔案或專案的待辦事項列表。
範例
/**
 * [...]
 * @todo   修正嵌套表單(nested list)的游標停留(hover)問題
 * [...]
 */
@group 暫定標籤
標籤名稱 @group
位置 檔案註解、區段註解、標準CSS註解
狀態 暫定標籤;第三方標籤,用於CSSEdit
備註 到目前為止這個標籤並沒有明確的用法,這是來自於相關廠商的建議。

附錄

標籤值列表
  • 文字 (Text):簡單的文字,可能會橫跨多行。
  • 布林值 (Yes/No):一種很基本的資料型態,CSS支援布林語句或是yes/no,它可以是「0」或「1」、「yes」或「no」、「true」或「false」。
  • 日期 (Date):有些標籤需要指定日期值,撰寫日期的格式應該參考ISO 8601。如果日期太大或是跨國的計畫,則推薦使用世界標準時間(Coordinated Universal Time,簡稱UTC)
  • 時間戳記 (Timestamp):CSSDOC草案尚未確定。
  • 參考來源 (Reference):CSSDOC草案尚未確定。
  • CSSDOC指令 (CSSDOC command):CSSDOC指令是從既定指令中選擇一個。有些指令擁有自己的參數與語法。以下是CSSDOC的指令:
    • parsing on
    • parsing off
    • version

  • 區段名稱:CSSDOC草案尚未確定。
瀏覽器列表

CSS的作者也許不知道該如何為瀏覽器統一命名,CSSDOC也在處理瀏覽器的表示法。現在市面上盛行著許多不同的網頁瀏覽器,不可能用一種表示法來統一制定。以下是CSSDOC建議的部分瀏覽器表示法,但這並不是強制規則,僅作為參考而已。

表示法 瀏覽器 版本 作業系統
Fx 2 nix Firefox 2 Linux/Unix
  Icab    
Ie 6 win Internet Explorer 6 Windows
Ie 3.2 os9 Internet Explorer 3.2 Apple OS9
  Konqueror    
lynx Lynx 所有版本 所有平台
Moz 1 osx Mozilla 1 Apple OSX
  Netscape    
Opera 6.5 win Opera 6.5 Windows
  Safari