:::

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    

訂閱： 張貼留言 (Atom)