:::

CSSDOC標籤參考表

布丁布丁吃布丁

CSSDOC標籤參考表

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    
(more...)

CSS寫作風格:CSSDOC介紹

布丁布丁吃布丁

CSS寫作風格:CSSDOC介紹

image

CSSDOC階層樣式表(Cascading Style Sheets,簡稱CSS)的一種寫作風格,可以幫助個人開發者與開發團隊改善CSS檔案的寫作/整理/管理等各方面的問題。CSSDOC使用知名的JavaDoc作法,以註解區塊(DocBlock)形式為原始碼寫作註解。它將CSS的格式、DocBlock註解以及註解使用的標籤(tag)整合在一起,為CSS檔案規範統一的寫作風格。

目前CSSDOC發展到2008年11月的第二次公開草案。CSSDOC的知名度不高,實際上這份草案也有很多未完成的部份。儘管如此,CSSDOC對於統一CSS的文件註解格式來說,已經是個可以參考的寫作指南。

就如CSSDOC所說,通常設計師撰寫CSS的風格並沒有統一,因此在交流CSS時會造成許多不方便。所以我想簡單地介紹一下CSSDOC的特色與用法,藉此也好好學習良好的CSS寫作風格。

 

使用CSSDOC的好處

儘管CSS寫作跟一般的物件導向式的程式語言不同,使用CSSDOC仍可以為程式設計師帶來幾個點好處:

統一寫作風格,促進程式交流

CSS設計師可以用CSSDOC來美化CSS檔案的版面,依此作為寫作風格的參考,以方便跟其他作者、作家、設計師、網頁開發者、創意指導等相關人員分享程式。

詳細註明相容性、錯誤修正與區隔設計

CSSDOC教導設計師跟軟體開發者如何在CSS的檔案中註明相容性、針對不同瀏覽器的錯誤修正與區隔設計的方法,讓開發與設計時可以更清楚地知道該段CSS語法的用意。

便於分析CSS檔案

撰寫的CSSDOC的CSS程式可以利用程式工具來剖析出額外的資料,就像JavaDoc可以產生標準格式的說明網頁一樣,目前也有利用Ruby實作的工具可以使用。

註解與文件區塊(DocBlock)介紹

CSSDOC採用類似JavaDoc的文件區塊(DocBlock)來撰寫CSS的文件,因此有必要先介紹一下文件區塊的樣貌。

/**
 * Short Description
 *
 * Long Description
 *
 * @tag   I am a tag named "tag"
 * @other And I am a tag named "other"
 */

上面是一個文件區塊(DocBlock)的例子,撰寫CSSDOC的資訊都會在文件區塊當中。在這個例子中包含了短敘述(Short Description,通常是一行)跟長敘述(Long Description,實際上可能是好幾行的敘述),還有以「@」開頭的「@tag」跟「@other」標籤與後面接著的值,用來標示這個文件區塊的後設資料。

所謂的CSS註解,是以「/*」開頭、「*/」結尾,這之間的資料是給設計師閱讀、電腦會自動省略的區域。文件區塊則是以「/**」換行開頭(注意,多了一個*喔!)、最後一行以「*/」結尾的區塊。在閱讀時十分地顯眼。

有使用過JavaDocPHPDocJSDoc等各種註解的程式設計師,應該都很熟悉這種寫作風格。許多IDE也都支援文件區塊的寫法,你只要輸入「/**」開頭,按下Enter鍵之後,IDE就會自動幫你把後面的「 */」帶出來。

由於CSS並不是很正規的程式語言,所以它的文件區塊用法以及裡面的標籤與Java或PHP有些許不同。CSSDOC使用文件區塊將CSS檔案分成各個部分,也利用文件區塊來註明CSS特有的CSS修正與區隔設計用法。

CSS檔案的結構

image在撰寫CSS的時候,一般我們會覺得CSS檔案結構很模糊。事實上我自己寫的時候,也常常隨處插入一個CSS語法,造成往後整理CSS時發生不少混亂的問題。

CSSDOC將CSS檔案區分成許多區塊來讓文件架構更為明確,如右圖所示。區塊分成兩種:檔案註解(File Comment)、區段註解(Section Comment),他們都是以文件區塊的方式撰寫而成。

檔案註解 (File Comment)

檔案註解位於檔案的開頭,一份CSS檔案只有一個檔案註解,目的是說明整份檔案的概要。

以下是檔案註解的範例:

/** 
 * Homepage Style
 *
 * Standard Layout (all parts) for Big Little Homepage
 *
 * This style has been designed by Mina Margin. It reflects
 * the composition of colors through years
 * customers project as well the boldness it implies.
 *
 * @project Big Little Homepage
 * @version 0.2.8
 * @package xhtml-css
 * @author Mina Margin
 * @copyright 2008 by the author
 * @cssdoc version 1.0-pre
 * @license GPL v3
 *
 * @colordef #fff; white
 * @colordef #808080; standard grey
 */

除了短敘述(Homepage Style)與長敘述(Standard Layout……. it implies.)之外,還有包含數個標籤。各標籤的意義簡單介紹如下:

  • @project:專案名稱
  • @version:檔案版本
  • @package:標示該檔案跟其他某些檔案一樣歸屬於某個包裹(package)中
  • @author:作者
  • @coptyright:版權聲明
  • @cssdoc:標示使用的CSSDOC版本
  • @license:標示此檔案的發行條款
  • @colordef:指定顏色的色碼以及其名稱
區段註解 (Section Comment)

區段註解位於檔案之中,可以省略或是有多個區段註解,它用以說明一個區段的開始。區段註解會包含「@section」標籤,而區段底下還可以分出「子區段(subsection)」,使用「@subsection」標籤。範例如下:

/**
 * Reset Section
 * 
 * @section reset
 */

[...]

/**
 * Reset Forms
 * @subsection forms
 */

[...]

如果你需要使用CSS修正(CSS Fixes)或是針對不同瀏覽器製作的CSS區隔設計(CSS-HACKS),你也可以加入額外的區隔設計註解(Hack-Comment)。以下是一個區隔設計中CSS修正的範例與CSS語法,這是用來迴避IE5的顯示錯誤而撰寫的。

/**
 * IE/Win Guillotine Bug
 *
 * @workaround
 * @affected IE 5.x/Win, IE6
 * @css-for IE 5.x/Win, IE6
 * @valid yes
 */
* html body a,
* html body a:hover { background-color: transparent; }

這段區段註解包含了短敘述(IE/Win Guillotine Bug)以及數個標籤,說明如下:

  • @workaround:標示這是一個解決程式錯誤的迴避方案(workaround),他並不能真正地解決程式的錯誤。
  • @affected:標示錯誤修正(bugfix)或是替代方法(workarond)的目標瀏覽器
  • @css-for:標示這段CSS語法是為了這些目標瀏覽器而撰寫的
  • @valid:是否已經驗證了這段CSS語法

標籤 (tag)

標籤包含在文件區塊中,以「@」開頭呈現。文件區塊中標籤的用處是類似後設資料(Metadata),跟我們現今常見的社會性標籤是不同的意思。

從上面的例子中可以看到,標籤是以更有格式的形式說明特定的資訊。例如檔案註解裡面使用「@project Big Little Homepage」的標籤與標籤值,就能夠說明該檔案的專案名稱為「Big Little Homepage」。目前CSSDOC草案規範中標籤的值僅接受英數字與常見的標點符號,中文字似乎並沒有在規範內。

規定的格式不僅讓人便於閱讀,CSSDOC的分析器也能夠更準確地分析出各個註解的意義與關聯。在CSSDOC第一版草案中設計了32個推薦標籤,也有4個廢棄的標籤。我試著將他們分成六類:

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

熟知各個標籤的意義與用法是了解CSSDOC的必要功課,詳細的內容就請參考PDF中第三節的內文,或是我另一篇整理的CSSDOC標籤參考表

結語

老師曾經說過一種句話,「要讓人家覺得你很專業,就要說這一行的行話」。如果要讓Java程式寫得看起來很專業,要學會使用JavaDoc;要讓PHP看起來很專業,要學會使用PHPDoc;那麼要讓CSS寫起來很專業,我想可以試著從CSSDOC開始。

編輯CSS的IDE編輯環境很多,但是支援CSSDOC的IDE卻不常見。我使用的Aptana Studio跟NetBeans都各自用各自的CSS註解,而不是使用常見的註解區塊。由於自己已經習慣了註解區塊與標籤的寫法,讓我在撰寫CSS時有也種不這樣做就渾身不對勁的感覺。至少沒有註解區塊的CSS,看起來就是一整個混亂且難以維護。所以我現在正學著使用CSSDOC來設計CSS檔案。

不過,CSS技術已經發展多年,但是CSSDOC的消息卻仍停留在2009年,至今也還沒有正式版本出來,前景真是令人堪憂啊。

(more...)

阿給USB攜帶給電器運作不正常

布丁布丁吃布丁

阿給USB攜帶給電器運作不正常

 

image

我買了阿給USB攜帶給電器,想靠它完成電池充電、行動給電的任務,但是沒想到它的充電供電功能都有問題!而且我還跟店家換過新的,依舊無效。投訴給士林電機也沒有下文,讓人十分怨嘆。

於是我打算把這個產品的問題狀況寫出來,希望不要再有人像我一樣傻傻地去買這個產品了。就算牌子有名也沒有品質保證,真是令人心寒。

阿給USB攜帶給電器簡介

5071615950_dd6d3d2c88_b 5071008935_fe39def5b5_b

士林電機的Dendee系列在很久以前推出了「阿給USB攜帶給電器」這個產品,它本身是可以透過USB對電池充電,也可以藉由將電池的電透過USB接孔釋放給其他裝置,以此可以用來幫手機充電。依照內裝電池規格不同,有給一顆AA電池的型號,也有給兩顆AAA電池的型號兩種。上圖是我買的AAA電池型號的那種,購買時即會附贈AAA電池兩顆。

購入與發生問題過程

我在半年前於光華商場購入阿給USB攜帶給電器(以下簡稱為「阿給」)AAA電池的型號,購入金額四百多。

買回家之後當然是先利用阿給來幫附贈的電池充電。我把電池裝好,利用交流電轉USB的插座來提供USB電源給阿給,並確認阿給的紅燈有亮起,表示正在充電,就讓他放著充了一整晚。

隔天早上我將阿給帶出門,裡面裝著應該是充飽電的電池。大概下午時快沒電,我就將阿給接到ASUS P750手機上充電。儘管一開始手機上是顯示充電中的訊息,但奇怪的是充電了半小時多,也不見手機電量有上升。拔掉阿給看看,發現電量不增反減。再給手機充電,沒想到再過一下子,手機就離開充電狀態。也就是說,阿給已經沒辦法供電了。

「該不會是買到機王了吧。」(剛好買到故障品的意思) 我當晚回去再將阿給充電,然後又裝到手機上測試,阿給依然沒辦法幫手機給電。

我隔天跑去光華跟店家反應商品有問題,店家檢測跟我說「電池根本就沒有充電」,我非常驚訝。阿給接著的USB電源轉換器是我平時就拿來幫手機充電的工具,而後來檢查結果的確不是USB充電器的問題。我回去再嘗試用阿給幫電池充電、放了一整晚,而隔天仍然是一樣的問題,於是過去光華要求店家換另一個阿給商品,店家也很無奈地換了一個新的給我。

結果,換了一個之後,另一個阿給仍然沒辦法充電、給電。

問題檢測

對於阿給的各種問題,我做了以下的測試:

電池有問題?否定

我試著換一組電池,不使用阿給附贈的Dendee AAA電池,改用平時給羅技M5050無線滑鼠使用的充電電池,並確保他的電量的確是足夠無線滑鼠使用,再裝在阿給身上給手機充電。結果當然是無法供電給手機。

原本在阿給裡面無法給電的Dendee電池,也確定電池裝到無線滑鼠中是沒有電力的。我改用之前我在用的便宜充電器幫阿給贈送的Dendee電池充電,然後再擺到無線滑鼠中,確認電量足夠且可使用,沒有問題。

基於以上測試,我認為不是電池的問題。

手機有問題?否定

店家質疑我是否是因為ASUS P750這個Windows Mobile的手機太過特殊所以無法供電。我說明一下,P750是接USB公-USB mini公接線來充電。線材本身是我本來就用來幫手機充電的線材,因此排除線材問題。

我也借了另一台T-Mobile G1來充電,這隻是Android首款的手機。但結果不僅是一樣無法供電,還充不到10分鐘就跳出充電模式,阿給就已經沒電了。

後來我使用HTC Hero來測試,也一樣是不行。

阿給的充電功能有問題?肯定

從電池的測試結果也可以知道,阿給本身的充電功能就有問題。

阿給充了一整晚,電池的電量沒有增加多少。所以光華商場的店家才以為我根本就沒幫電池充電。相反地用其他充電器幫同樣的電池充電,就可以用於無線滑鼠上。可知阿給沒辦法扮演好充電器的角色。

阿給的供電功能有問題?肯定

同樣的,我用其他充電器幫電池充飽電,並確定在無線滑鼠上可以正常使用,再放到阿給中給手機充電。但是他還是一樣無法完成供電的任務。由此可知,即使是電量充足的電池,阿給的供電功能本來就有問題,也就沒辦法供電。

反應給廠商,沒有下文

我將問題反映給士林電機的客服人員,問題內文如下:

您好,我於三個月前購買了貴公司的「阿給USB攜帶給電器」(AAA電池版本),發現它的功能並沒有正常運作。

1. AAA電池充電:我把包裝隨付的兩顆電池裝上,插在有供電的USB槽上一整晚,然後放到無線滑鼠上使用,發現他幾乎沒有充到電,用一下就沒電了。這跟我使用另外的充電器充電比起來,就有感覺到明顯的差異。

2. 給電器:我將2顆AAA電池以其他確定可以正常運作的充電器充電,然後再放到阿給USB攜帶給電器,接USB線給HTC Hero手機充電。運作時阿給並沒有燈號指示,而電池有微微溫度上升,我想這是正在給電的意思,而HTC Hero手機也是有正在充電的訊息出現。可是大概放了一段時間,HTC Hero手機的電量不增反減,這個意思究竟是?

我是在光華商場購買,在購買之後幾天就發現這個問題,並請店家換另一個新品,可是狀況還是一樣。

我不確定是兩個新品都是一樣的問題,還是貴公司的阿給USB攜帶給電器確實無法達到包裝上聲稱的「電池充電」、「USB給電」功能,可否請貴公司幫我解惑呢?

image

過不久,士林電機客服人員回信給我,說會主動聯繫並解答。但是等了快一個月了都沒有下文,我猜這封信大概只是機器人發出來的自動回應罷了。

結語

我在網路上查了一下其他人的使用經驗,Mobile 01討論串中有人提到他供電時有的問題、PDA只能充4%電力,也有人回應說N82可以充個3格、有人更表示充電只能用附贈那兩顆電池;另一邊也有人說他N73連一格都充不飽

也許可能我運氣真的很差,換了兩台阿給都是有問題的機王。本來想說不能供電算我錯估普通電池跟手機電量的需求,那就算了,沒想到連作為充電器都辦不到,這就讓我感到非常的難過。

撰寫本篇特此警示,提醒其他人切勿購買阿給USB攜帶給電器!

(more...)

我的論文備份策略:Dropbox

布丁布丁吃布丁

我的論文備份策略:Dropbox

image

Dropbox是一個知名的免費雲端檔案同步工具,他能滿足我對於檔案備份的多個需求,包括全自動、雲端、版本備份。一開始帳戶提供了2GB的空間,可以再透過完成開始教學動作(+250MB)、註冊學校信箱(+512MB)、邀請其他使用者(+256MB每人/+512MB每學生),最大可以到18.3GB的免費空間。

其實我自己也是希望能夠推薦這個好工具給大家使用,並且藉此提昇自己的Dropbox容量XD 如果你看完這篇介紹之後也想開始使用Dropbox,請多多使用我的邀請連結喔!

 

布丁邀請註冊Dropbox連結

備份的需求

在介紹Dropbox之前,有一個問題是需要先思考一下:究竟你認為理想的備份策略是什麼呢?一般來說,備份的目的在「一旦資料遺失或損毀時,還可以很快地取得原來或最近備份的資料,讓工作可以繼續正常地進行」。長時間與電腦共處,以電腦作為主要生產工具的人都知道,電腦其實比想像中的更容易故障!重要的資料不僅要備份,還要透過雲端服務異地備份,更要自動化進行。

我撰寫論文期間很長,為了避免資料遺失,備份是必要的工作。我的論文資料不僅包含單純的Microsoft Word檔案,還有為了論文撰寫的大量網頁程式、圖片、各種規劃資料、還有寫這個Blog使用的Windows Live Wrtier程式與草稿。資料夾不僅分散各處,還會時常更改。如果要以手動方式進行備份,每次都會是相當浩大的工程。

基於以上情況,我將備份的需求歸納為以下四點:

備份要自動進行

我撰寫論文的工作日日夜夜都不斷進行,常常做到興頭上就忘記還需要進行備份作。儘管聽說有人會利用Gmail寄信來備份各版本的文件,但是像我論文的資料這麼多,每次要壓縮、上傳來進行手動備份,就會花去相當多的時間。而且由於資料眾多,手動備份顯然不是個好方法。

能夠以排程或是自動偵測的方式進行的備份功能,才能真正地讓你「幾乎忘了他的存在」,也是我選擇備份策略時第一個考量的重點。

透過雲端服務達到異地備份

有人會將資料複製到隨身硬碟中保存,可是日前就有人的筆記型電腦跟備份硬碟一起被偷的新聞,這也告訴我們異地備份的重要性,換句話說,就是「雞蛋(電腦)不要放在同一個籃子(地方)」的道理。

雲端服務是達成異地備份的方法之一。透過網際網路來將資料保存在不同地方的電腦中,即使資料在其中一台電腦的毀損或遺失,另一台電腦仍能保有最新的資料。使用雲端的先決條件就是要時常連上網際網路,而現在撰寫論文、程式時通常都需要開啟網際網路來查詢資料,也就是說,進行工作與備份檔案都會需要利用網際網路進行。沒有網路就不想工作啦 。(誤)

多資料夾備份

我的論文相關重要資料分散在電腦的各處:論文本文會放在桌面的資料夾中、程式會擺在伺服器的運作資料夾、Firefox的Zotero書目資料放在Firefox的資料夾底下。因為需要備份的資料太過零散,手動備份會非常地麻煩,因此需要工具來協助。

其實大部分的檔案同步服務都可以設定多資料夾來進行備份,而Dropbox搭配Dropbox Folder Sync之後,也能提供多資料夾備份的功能。

多版本備份

一般檔案同步的功能通常是做到更改、刪除時即時地變更各地的檔案。然而,這個特色也有個盲點:當你一不小心把檔案刪除或甚至是把檔案內文清空並儲存時,各個同步的資料也跟著一併刪除或清空,造成無法挽回的悲劇。這是自動化備份先天的限制,使用的時候必須要有所認知。

然而為了避免發生這個窘境,Dropbox的一大特色在於多版本的備份。每次Dropbox在備份資料時,都會在遠端空間上保存舊版本的資料,30天內的變更資料都會完整保存,方便你將資料隨時還原到之前儲存的任一版本。連異塵行者也是因為Dropbox的版本備份救了他的一命而對此讚揚不已

本篇介紹的Dropbox幾乎可以滿足四點備份的需求,操作也相當地簡單。因為Dropbox全自動的關係,所以安裝完、設定完之後就可以放著讓他自動運作,非常方便!

介紹Dropbox的相關文章

網路上介紹Dropbox的文章非常地多,因為大家介紹都很詳細了,所以這一篇我也就不做太多圖文細節介紹。以下大概介紹一下各篇所寫的重點:

入門篇
空間加大篇
其他應用篇

Dropbox檔案同步運作介紹

Dropbox最重要的仍然是檔案同步的功能,然而並不是每個人都有「檔案同步」的概念,所以在此先從整體的運作架構來介紹。

image

Dropbox的運作大致上可以分成三個部分:遠端空間Dropbox本地端儲存資料夾My Dropbox、以及連結兩端的Dropbox工具(需要安裝在本地端電腦上)。其中本地端就是指你的電腦主機、筆記型電腦、或是智慧型手機。基本的檔案同步運作步驟如下:

  1. 使用者將要備份的資料存在本地端My Dropbox資料夾中。
  2. Dropbox工具會透過網路自動地確認My Dropbox的資料更新狀況。
  3. 本地端較新的資料會上傳到遠端空間Dropbox。
  4. 本地端將較舊的資料從遠端空間下載回來更新。

透過Dropbox工具時常地確認本地端與遠端空間的資料,不論你在哪一台電腦/手機/筆電編輯,只要他們時常跟Dropbox保持連線,就能你的資料一直保持在最新的狀態。當然,這個前提是要必須時常保持網際網路連線,或是在要更新時進行連線才行。

Dropbox工具

不同的作業系統或環境都有各自的Dropbox工具。目前Dropbox提供了電腦的Windows、Mac、Linux(包括Ubuntu、Fedora兩種發行版)、手機(iPhone、iPad、Android、Blackberry),支援範圍非常廣泛。Dropbox的安裝方式非常簡單,你也可以看免費資源網路社群的圖文介紹來了解個大概。

image 

安裝Dropbox工具的同時,也會協助你上網註冊Dropbox帳號、建立遠端空間,並且配置本地端儲存資料夾My Dropbox。

image

我習慣將My Dropbox放在桌面上,方便配置與找尋資料。

image

Dropbox工具安裝完成之後會常駐在系統當中,以Windows來說就是會放在右下角的通知列。點選右鍵可以看到快速功能以及目前空間的使用狀況。

安裝完Dropbox工具、配置好My Dropbox資料夾之後,基本上就可以讓他放著自動去進行同步備份工作而不需要理會了。

本地儲存資料夾My Dropbox

image

當資料夾被設為My Dropbox資料夾之後,裡面的檔案在左下角都會有特殊的標誌。綠色打勾表示已經同步、藍色箭頭表示同步中,此外還有一些其他顏色的標示,但只要確認這些檔案都有綠色打勾,就表示同步狀況正常。

你可以將任意的檔案放入My Dropbox資料夾,讓Dropbox幫你進行檔案同步的動作。但是Dropbox只會備份My Dropbox一個資料夾的限制實在是很不方便,這時候就要借助Dropbox Folder Sync這個強大的小工具來達到多資料夾備份的目的,讓你不需要變更原本電腦中的資料架構也能進行備份。

上圖在我的My Dropbox中,「kals」是位於網頁伺服器中的程式檔案資料夾、WindowsLiveWriterPotable是位於Program Files的資料夾,這些都是透過Dropbox Folder Sync來進行連結的資料夾。關於Dropbox Folder Sync詳細的安裝與配置方式,就請看電腦玩物的介紹吧。

Dropbox Folder Sync功能非常重要,事實上我也是發現它之後才真正使用Dropbox來進行備份。畢竟像是程式之類的檔案都有既定的架構配置,不可能隨意把它改名叫做「My Dropbox」,而各種需要備份的資料混在同一個My Dropbox資料夾裡也是不方便管理。所以多資料夾備份也是我認為檔案備份的需求之一。

遠端空間Dropbox

image

當你擁有Dropbox帳號之後,你就可以到Dropbox的網站上去瀏覽、取用你同步的所有資料。遠端空間的資料會跟你本地端My Dropbox中的資料完全相同,一般情況下是不需要開啟遠端空間,只要在My Dropbox管理檔案即可。不過,就算你不使用檔案同步功能(沒有My Dropbox),你還是可以把它當成一個2GB以上的免費空間使用。

image

在Dropbox網站的遠端空間網頁介面中可以進行檔案分享、版本控制、回溯已刪除資料等動作。上圖即是我的備份檔案之一「KALS UML規劃.uml」的各個版本,每次我存檔的版本Dropbox都鉅細靡遺地把它備份下來,最短甚至一分鐘內就是一個版本。每當我檔案誤刪、誤改時,我都可以在此輕易地將檔案還原到之前版本,非常方便。

桌上型電腦、筆記型電腦同步備份工作

5070597991_83eba78b9c_b

我大部分時候是在桌上型電腦工作,但是有時候需要出遠門去處理事情,這時就會帶著筆記型電腦出門。我在桌上型電腦跟筆記型電腦都配置了Dropbox,甚至利用Dropbox Folder Sync將多個資料夾都配置完畢。這樣子我在桌上型電腦撰寫的程式可以利用Dropbox輕易地同步到筆記型電腦中,讓我即使出門也可以用桌上型電腦的資料來繼續撰寫;而要切換回原本的桌上型電腦時,也一樣透過Dropbox來將筆記型電腦中更新後的資料存回桌上型電腦。

更重要的是,檔案同步都是全自動進行,我不用考慮現在使用哪一台電腦才是最新的資料,我需要的只是花點時間讓Dropbox連上網路進行同步作業而已,這才是理想的檔案同步策略啊。

結語

這篇的目的是在介紹我如何使用Dropbox來備份我的論文資料,許多操作上的細節或是Dropbox的其他功能,就請你參考上述整理的文章連結吧。

最後如果你覺得Dropbox很棒,也想跟我一樣用Dropbox備份你電腦中的資料的話,也請多多利用我的邀請連結來註冊一個Dropbox玩玩吧XD

 

布丁邀請註冊Dropbox連結

(more...)

圖片上傳與Plurk貼圖的好工具:ZScreen與ImageShack

圖片上傳與Plurk貼圖的好工具:ZScreen與ImageShack

image

我習慣於用Plurk來寫個圖文兼具的噗,而Plurk中要貼圖必須要先上傳、取得網址才能完成這個任務,操作手續繁雜。再者Plurk內建的圖片伺服器並沒有提供像ImageShackFlickr這種專門為圖片、影片典藏網站一樣的管理介面,上傳之後就無法再管理,要取得舊有圖片也是不方便。

後來我發現可以使用ZSCreen這個強大的工具來解決上述的問題,讓我可以快速地截圖、上傳圖片到指定的網站(如ImageShack)、並且方便地將圖片連結放到剪貼簿中。

Plurk貼圖之不便

你有在使用Plurk寫微網誌嗎?我非常習慣於使用Plurk來記錄事物,像是一邊寫論文的程式,一邊記錄一下現在做到哪裡、狀況如何、下一步該做些什麼。這樣能夠讓我方便日後將這些零碎的資訊彙整起來撰寫成一篇較為完整的Blog。

image

Plurk的特色在於可以在簡短的140字中提供圖文兼具的內容,只要貼上圖片的網址,最後即能顯示圖片的縮圖,別人也能點選縮圖看到更大的圖片。上圖即是早上我分享Astrid小章魚待辦事項工具的更新消息,貼個小章魚圖片可以讓同樣使用這個軟體的同好更容易發現這消息。

image

說實在的,Plurk的貼圖功能實在是不好用。首先要先從「分享 > 圖片」中打開「分享圖片」的對話視窗,選擇檔案,按下「上傳圖檔」,等待圖片上傳,然後再繼續寫你想要寫的內容。

其實這個動作最終目的也不過就是要取得一個圖片上傳的網址,但是這些等待動作卻可能會打斷寫作的思緒。

另一個問題在於利用原本的上傳功能上傳到Plurk的圖片伺服器之後,使用者就沒辦法管理那些已經上傳的圖片,而圖片也會被強制縮圖、無法展現原本的大小。他不像ImageShack或Flickr這種圖片或影片典藏網站一樣具備豐富的管理功能,使用者更無法回溯以前自己上傳的圖片。這對像我這種利用Plurk記錄生活點滴的使用者來說是非常不方便的缺點。

因此,我需要透過第三方的服務來協助我典藏圖片與上傳圖片。我使用的圖片典藏網站是ImageShack,而圖片上傳工具就是本篇的主角ZScreen了。

ZScreen簡介

由於重灌狂人介紹了ZUploader這個好用的圖片、檔案、文字上傳軟體,連帶地也讓我發現了ZScreen這個比ZUploader更為強大的工具。

ZScreen功能不僅具備原本ZUploader可以做到的上傳功能,還有各種豐富的功能可以使用。第一次開啟來使用時,我在SCreen的複雜介面中摸了好久才知道個大概,甚至有部分功能是看了網路上簡睿隨筆的ZScreen:一氣呵成的單鍵「抓圖與傳檔」工具才知道原來還有短網址功能。

image

ZScreen還有一個很重要的功能,除了可以用匿名身分上傳之外,還可以用已註冊會員的身分上傳到目標位置,包含FTP、本地端主機、RapidShareSendSpaceFlickrImageShackTinyPicTwitterImageBarnMindTouch等你可能聽過也可能沒聽過的空間。這個功能讓我們可以方便地將圖片上傳到自己慣用的圖片典藏網站中,已方便進行圖片的管理。

免費圖片、影片典藏網站:ImageShack

image

這隻黃色樹蛙是老牌多媒體典藏網站ImageShack的招牌圖示。ImageShack的特色在於免費、穩定、上傳無限空間、提供圖片直接連結(這樣子才能在Plurk上顯示,而不是一定得連到該網站才能開啟圖片),他也有很多第三方工具來協助上傳,像ZScreen就是這類型的工具之一。

image

註冊免費會員之後,使用者可以利用「My Images」功能方便地管理上傳的圖片、影片,而沒有像Flickr免費會員只能看200張的限制。根據使用條款的說明,註冊會員的圖片將會永久保存而不會被刪除。當然,前提是不要觸犯暴力及色情的使用條款限制。

我現在多使用ImageShack來保存圖片,而在以下ZScreen介紹中也是使用ImageShack作為上傳圖片的目的地。如果看到這邊你也覺得很有興趣的話,歡迎點此註冊一個免費會員來玩玩!

設定ZScreen上傳到ImageShack

安裝ZScreen、註冊ImageShack的操作不難,但是要在ZScreen介面中設定上傳目的為ImageShack,則需要摸索一陣子。我假設正在看這篇文章的你已經安裝了ZScreen,也已經註冊了ImageShack,那麼接下來就是教你怎麼在ZScreen裡面進行設定。

取得ImageShack的Registration code

image

ZScreen必須設定你在Image Shack的User Name(使用者名稱)跟Registration Code(註冊碼)。User Name在註冊的時候你應該已經設定了,不過Registration Code則是要註冊完畢之後到My Images –> Preferences(偏好設定)裡面才能查詢。其中「My ImageShack Registration Code」底下的表單則是Registration Code,看起來就像是一串很長的亂碼。

選擇ZScreen上傳目的為ImageShack

image

請打開ZScreen的主介面「Main」,並在「Destinations」的「Images:」中選擇「ImageShack – www.imageshack.us」。

設定ZScreen中的ImageShack

image

一樣是在ZScreen的視窗中,從上排導覽頁中選擇「Destination」,再從次導覽列中選擇「ImageShack」。你會看到ZScreen需要你填入Registration Code跟User Name,請你將ImageShack中的資料填入即可。

如此設定完畢之後,透過ZScreen上傳圖片資料就會自動傳到ImageShack囉。

使用ZScreen擷取、上傳圖片

接下來我來利用ZScreen的Screenshots(圖片擷取)功能,來一氣呵成地擷取網頁圖片、直接上傳到ImageShack、取得圖片網址等一連串的動作。

開啟圖片擷取功能

image

ZScreen可以利用快速鍵、在通知列中的圖示按右鍵並進入「Quick Actions」、或是開啟Actions Toolbar來啟用擷取功能。擷取螢幕的功能有:

  • Entrie Screen:擷取全螢幕,預設快速鍵為PrintScreen鍵。
  • Selected Window:選擇部分視窗,預設快速鍵為Shift + PrintScreen,他會提示你選擇要擷取的範圍,可以是整個視窗、視窗中的一個元件的部份等,相當方便。
  • Crop Shot:擷取自訂範圍,預設快速鍵為Ctrl + PrintScreen,他會提示你選擇要擷取的範圍,畫面上會有尺規方便你度量。
  • Last Crop Shot:擷取上一次的擷取範圍,沒有預設快速鍵。
  • Auto Capture:詳細的擷取功能,可選擇延遲擷取的秒數,如下圖。沒有預設快速鍵。
    image
利用Selected Window選擇要擷取的範圍

image

利用「Selected Window」功能可以準確地選擇要擷取的網頁範圍,請用上述的方法來啟用「Selected Window」擷取功能吧。

上圖是正在使用Selected Window的擷取功能,你可以看到ZScreen會用紫色的尺規框線來提示你要選取的範圍。移動滑鼠的同時,他也會隨之改變選取範圍。他會很聰明地辨識視窗的元件與範圍,讓你快速抓到要擷取的網頁內容。確定要擷取的範圍之後,按下滑鼠左鍵即可完成擷取。

ZScreen自動上傳

image

擷取完成之後,通知列的ZScreen圖示會變成橘字,這表示ZScreen正在處理上傳圖片的動作,請稍待片刻。上傳完成之後,ZScreen就會顯示上傳完成的提示,如上圖。而上傳的圖片網址也自動地放到你的剪貼簿去了,你可以用貼上快速鍵「Ctrl + v」來將網址貼到你正在書寫文字的地方:

http://img63.imageshack.us/img63/2171/ss20101010235921o.png

在Histroy查詢已上傳的圖片

image

透過ZScreen上傳的資料會全部記錄在History功能中,你可以開啟ZScreen的視窗,並切換到「Histroy」頁籤,就可以輕易地取得之前上傳的各種資料。

ZScreen從剪貼簿中上傳圖片

雖然他的螢幕擷取功能很豐富,但我個人仍偏愛使用FastStone Capture來截圖、編輯,然後將圖片複製到「剪貼簿」,再請ZScreen「上傳剪貼簿資料」來進行貼圖。

利用各種編輯工具完成圖片,並且複製到剪貼簿

image

上圖是利用FastStone Capture編輯完成後再FastStone Editor編輯的畫面,當我確定我圖片可以上傳之後,只要按下「Ctrl + c」複製此圖片,就可以準備利用ZScreen進行上傳了。

ZScreen上傳剪貼簿資料

跟擷取螢幕的功能一樣,你可以從通知列的ZScreen圖示上按右鍵並進入「Quick Actions」、或是開啟Actions Toolbar來啟用Clipboard Upload(上傳剪貼簿資料)功能。

  • Clipboard Upload:上傳剪貼簿中的資料。預設快速鍵是Ctrl + F6

我個人習慣利用快速鍵Ctrl + F6來啟用上傳剪貼簿的功能。啟用此功能之後,跟擷取螢幕一樣地,通知列的ZScreen圖示會變成橘色字,再稍等一下就會顯示上傳完成的通知囉。

結語

我一直認為「工欲善其事,必先利其器」是一句至理名言。利用ZScreen來幫助我上傳圖片,我就可以一邊寫Plurk,一邊擷取並上傳自己要的圖片(或是備份原本已經在網路上的圖片),最後整合上傳圖片的網址與文字資料,寫出一則圖文並茂的訊息。日後我也能回去ImageShark來查看、整理之前上傳的圖片,而不必擔心當初寫在噗浪中的圖片在不知不覺中被人拿掉。

其實ZScreen還有很多功能可以使用,就等其他人繼續挖寶囉!

(more...)

論文進度報告(2010/10/10):幾乎完成工具列

布丁布丁吃布丁

論文進度報告(2010/10/10):幾乎完成工具列

image

上次的進度報告之後又隔了兩個多禮拜,最近也是一直在研究JavaScript的基礎技術,然後一邊在Blog把整理好的東西寫出來,希望能給一同鑽研JavaScript的程式設計師作為參考。評估各種寫作方式並訂定之後,就是繼續兩個禮拜之前停頓的進度,而繼續把工具列的部分完成。現在工具列只差「通知」功能尚未實作,但這是要等標註功能實作之後才會有通知,接著才是繼續完成這部份的功能。接下來就是要整理標註功能的UML了呢,又是一項大工程。在這之前,先來整理目前的論文進度吧。

目前的WebApp端的進度

元件 預估程式數量 已完成 UML類別圖
toolkit 17 17 1
core 15 13 1
kals_window 6 6 1
kals_toolbar 30 24 2
kals_text 38+? 0 3
search 6+? 0 1
統計 112+? 60 (53.5%) 9

整體來看,目前完成了大約一半的程式。由於使用物件導向架構開發,每個細節元件都是取用於toolkit或core中的上層元件,在開發同時也會不斷地改良這些元件,因此系統開發的速度會越寫越快。當然,這只是理論上而已。

也許會有人注意到類別程式的數量跟之前比起來有所減少,從之前的114降低到了112。我嘗試簡化系統的功能跟開發的方式來讓整個專案能更快完成,目前是將「自訂外觀」、「個人相片」的功能取消,暫緩適應小螢幕的功能調整(toolkit設計時有考慮小螢幕,但不一定每個功能都能適用就是);而開發中也只對關鍵功能設計單元測試,並且緊對Firefox進行測試,Chrome、IE、Android則在未來有機會時再進行統一的檢查。

navigation

上圖是kals_toolbar中navigation的UML類別圖,這是工具列上各個視窗的功能設定。其中灰字的類別則是暫停開發的類別。詳細的UML類別圖,請參考KALS Wiki

至於專案時程仍暫時維持在19天後完成,也就是10月29日。能不能完成我也沒把握,只能說盡力而為而已。

一改再改的JavaScript物件導向繼承寫作方式

一開始我的JavaScript是用最原始的prototype繼承法,但是由於這種方式在使用上會有些問題,而且我需要使用上層類別的方法,所以又花了一段時間回頭找尋相關資料學習。

首先學習到的是call跟apply的用法,但是發現到JavaScript仍有傳址問題存在,所以又把所有的屬性與方法寫在類別的建構子裡面,不過那將會造成系統資源大量消耗的問題,不得不再找尋新的方法。

接著找到的是Dean Edwards的Base繼承類別,他的確是很好用,寫法簡潔明瞭、又有呼叫上層類別方法的this.base()可使用,但是我使用的Aptana Studio看不懂,而我另外又試用了五六種JavaScript IDE,一樣是看不懂。儘管我後來找到讓Aptana Studio能夠理解的Base繼承法,但是最後仍毅然決然地使用最原始的prototype繼承法。

這是因為我在找尋這些方法的期間,學習到了prototype利用call、或是經典的base方法來呼叫上層或甚至是其他類別的方法來繼承並覆寫,讓prototype的寫法有了更多彈性,而能夠滿足系統的需求。儘管寫起來是比Base繼承法繁雜許多,但是由於prototype繼承法容易分析,許多JavaScript IDE都能理解,也是JavaScript程式設計師應該要知道的基本功課,這是我最後選用prototype繼承法來開發的原因。

這段期間不僅是一直翻閱相關資料、測試方法的優劣,還把系統的所有程式改寫了三次之多,著實非常地花時間,但也因此學到了不少東西。

重新檢視單元測試的必要性

core

在撰寫toolkit跟core的時候,我會要求自己盡量撰寫單元測試,並且最好是能夠測試到所以功能,也就是要求高「測試覆蓋率(Code coverage)」。上圖是core的UML類別圖,其中橘色的小註解標示著這部份的系統有設計單元測試的意思。小小的15個類別裡面,就有7個單元測試,力求核心元件要穩定。

過於繁雜的單元測試

上述在核心的工具時還可以做,到後面設計UI時,設計單元測試就越來越麻煩。我是用setTimeout來設計成機器人的方式,利用jQuery去選擇物件來點選元件或輸入資料,用以測試功能是否正常運作。但是這個機器人也常常做出一般人沒辦法做到的功能,導致測試的水準是比實際上更為高。舉例來說,原本使用者不可能點到某些隱藏起來的按鈕,可是用jQuery去點就可以點到、使用者必須等待視窗關閉並開啟之後才能執行下一個動作,可是jQuery就是無視視窗開閉來進行動作,導致他找不到下一個視窗的功能。也許是我設計單元測試的方法不對,但目前這樣做的確是很累,也顯得不切實際。

總結以上,簡單來說有兩個問題:

  1. 設計單元測試比設計元件本身還花時間,頗有本末倒置的情況發生。
  2. 單元測試不見得切合真實手動操作的情況。畢竟UI設計不像之前的計算用或存取用的程式這麼單純。

因此有必要重新檢討單元測試的必要性。

選擇重要的功能設計單元測試

仔細想一想,不需要全部功能都進行單元測試,去拼那個「測試覆蓋率」實在是很浪費時間與精力,只需要針對重要的功能設計單元測試即可。具體來說,針對具有以下兩種條件的功能來設計單元測試最為實用:

  1. 關鍵功能:千萬不能出錯的功能,當然要用單元測試確保他的正確性。
  2. 多道手續:與其說是在意其正確性,不如說是檢查時因為手續太多很麻煩,不如設計成單元測試的機器人讓他自己跑出的目標功能,再看看哪裡有問題,可以省下許多手動操作的時間。

也就是說,即使很重要的功能,但是如果很簡單就可以手動進行測試,或是其他測試中已經會使用到的功能,那麼就不需要刻意地撰寫單元測試。

程式要經過測試才算是完成。我仍然堅持這個最低底線,但現在並不強求一定要設計成自動的單元測試,即使是手動測試也可以算是勉強及格。

缺乏多人合作的遺憾

寫著寫著來講一個額外的小故事。

有天晚上回到宿舍的時候,發現室友學弟的位置旁坐著另一位學生。

學弟是資科所的學生,研究題目是跟雲端相關,當然也是寫程式的工作。看起來他應該是跟他同學兩個人正在趕一個系統,我偷偷地瞄到了phpMyAdmin的介面,兩台Mac筆電外加一個外接螢幕通通擺在桌上,旁邊還有喝到一半的五十嵐珍奶,看來晚上是要熬夜拼進度了。

老實說,我很少與人一起分工合作地寫程式。教人寫程式的經驗很多,但是可以像學弟他們那樣,「那個帳號登入的部份就拜託你了。」「OK!」地將一個系統分成幾個部分、再各自完成的經驗則是相當地少。不過架伺服器的各功能分工倒是有的,教育部計畫的時候,但那畢竟是功能調整,不太像是寫程式的這種「創作」。

我知道這種分工合作經驗的重要性對於程式開發來說並不亞於技術知識,大型的、有價值的系統是無法、也沒有時間讓我自己一個人完成,而我知道這正是我的弱點。至今我仍然是一個人在寫著程式,就像是現在正在做的碩士論文一樣。

儘管如此,我也在學著讓自己的程式「更好讀」、「更容易讓人使用」。像是建立嚴謹的物件導向架構程式讓人方便使用、遵守PHPDoc、JSDoc、cssdoc這種具有標準規範的註解讓人容易閱讀、利用UML跟網站草圖讓人理解整個系統,使用甘特圖與Wiki共筆工具來模擬多人合作時的專案互動。

我希望我能夠有資格與未來的夥伴一起合作開發一個大型的系統,所以我要加油,嗯。

結語

現在最令人擔心的是,19天後到底能不能完成系統呢?即使系統完成,後面還有好多後續的動作要做,多到讓人現在不想要面對的事情。能在這學期畢業嗎?能在明年3月之前如期把論文交給國中圖嗎?問題實在是太多了。現在還會有人問我要不要繼續念書,還是去當兵,還是要去當資訊替代役,但是現在能不能畢業都不知道啊XD

總之,每天都努力地繼續寫程式、寫Blog記錄,努力地向前進吧。

題外話,國慶日當天寫進度報告真是格外值得紀念?

(more...)

JavaScript物件導向繼承:以prototype方式繼承中需要呼叫constructor的問題

JavaScript物件導向繼承:以prototype方式繼承中需要呼叫constructor的問題

image

Dean Edwards認為更好的JavaScript物件導向應該有的其中一個條件是「I want to avoid calling a class’ constructor function during the prototyping phase」(在原形宣告期間,要避免去呼叫類別的建構子),這是由於JavaScript傳統的prototype繼承方式中,總是一直去呼叫父類別的建構子,才能讓子類別進行繼承。也就是說,父類別建構子裡面做過的事情,在該類別「真正派得上用場」之前,就得先做過一次,白白消耗客戶端的記憶體及運算時間。

這一篇是為了記錄究竟什麼是「原形宣告期間(prototyping phase)就呼叫建構子(constructor)」的問題,以及父類別的建構子裡面盡量不要使用太多動作的消極建議,最後簡單地介紹使用Dean Edwards的Base類別改善方法的優缺點。

JavaScript的prototype繼承方式

以下我舉一個簡單的JavaScript以prototype方式繼承的兩個類別「A」跟「B」,說明一併寫在註解裡面:

//建立類別A,以下是建構子(constructor)
function A() {
    //在畫面中輸出[Call A's constructor],表示執行A的建構子
    document.write("[Call A's constructor]");
}

//A的方法,稍後會給B繼承
A.prototype.method = function () {
    //表示執行A的方法
    document.write("[Hello, world!]");
};

//建立類別B,以下是建構子
function B() {
    //在畫面中輸出[Call B's constructor],表示執行B的建構子
    document.write("[Call B's constructor]");
}

//prototype方式的繼承。注意,此處呼叫了A類別的建構子
B.prototype = new A();    //畫面輸出[Call A's constructor]

//實體化類別B到變數b中
var b = new B();    //畫面輸出[Call B's constructor]

//呼叫由類別A繼承來的方法
b.method();    //畫面輸出[Hello, world!]

執行到最後,畫面上會輸出「[Call A's constructor][Call B's constructor][Hello, world!]」。然而理想上,程式的最後只有實體化類別B、沒有實體化類別A,因此應該只要呼叫到類別B的建構子,而不需要呼叫到類別A的建構子。但是實際上這種prototype繼承方式,卻是會在繼承時強制地呼叫類別A的建構子,造成資源的消耗。

設計建構子的心得

其實不僅僅是上述的問題,就連類別中的「物件類別(Object)」屬性也會受到JavaScript屬於傳址運作而可能遭受子類別影響的缺點(詳細請看我另一篇的討論),而必須在建構子中加入初始化屬性、並且呼叫父類別建構子。這即使在Dean Edwards繼承庫中,也會有一樣的問題。

換句話說,重複呼叫父類別建構子,似乎是難以避免的一個難關。在此前提之下,就是盡量不要在建構子中寫入太多程式、執行太多動作,最簡單的只要將物件類別的屬性初始化就好。

有些JavaScript程式設計師會在類別的建構子中宣告許多動作,但在建構子會被重複呼叫的前提下,這顯然地並不是很好的作法。舉例來說,以下就是在類別的建構子中宣告屬性與方法的JavaScript類別寫法,但是這會在每次呼叫建構子時重複地被執行、佔用記憶體,因此並不是很好的寫法。

function test() {
    var private1 = "I'm private variable 'private1'!";//私有成員變數
    this.public1 = "I'm public valiable 'public1'!";//公開成員變數
    function getPrivateFriend() {//私有成員函數
        alert(private1);
    }
    this.getPrivatePublic = function() {//公開成員函數
        getPrivateFriend();
    }
}

儘管如此,唯一令人欣慰的是,在繼承階層中最底層的子類別則就沒有上述的限制,因為他們不需要被別人所繼承,而他們通常也是系統中最常在建構子寫入大量動作的類別。

改用Dean Edwards的Base類別如何?

Dean Edwards針對這個問題提出了改良後的JavaScript物件導向繼承類別:Base (SkyDrive備份),這種方式可以避免呼叫到上層類別的建構子。

以下是上述範例中使用Dean Edwards的Base改良後的程式碼,請注意必須先引用Base.js喔。

<script type="text/javascript" src="Base.js"></script>
<script type="text/javascript">
//建立類別A,繼承自Base類別
A = Base.extend({
    //建構子
    constructor: function () {
        //在畫面中輸出[Call A's constructor],表示執行A的建構子
        document.write("[Call A's constructor]");    
    },
    method: function () {
        //表示執行A的方法
        document.write("[Hello, world!]");
    }
});

B = A.extend({
    //建構子
    constructor: function () {
        //在畫面中輸出[Call B's constructor],表示執行B的建構子
        document.write("[Call B's constructor]");
    }
});

//實體化類別B到變數b中
var b = new B();    //畫面輸出[Call B's constructor]

//呼叫由類別A繼承來的方法
b.method();    //畫面輸出[Hello, world!]
</script>

最後畫面上會輸出「[Call B's constructor][Hello, world!]」 ,由此可知他並不會呼叫到類別A的建構子,而且整體程式的排版更為直觀、易讀。

image

但是這種方法的缺點在於JavaScript IDE不支援,即使是我使用過最聰明的Aptana Studio也看不懂Dean Edwards繼承類別的運作方式,所以上圖的自動提示中是找不到類別B所繼承的方法method。

結語

其實一開始看到Dean Edwards提出這個問題時,我還看不懂這是什麼意思。直到實作了一段時間之後才發現原來建構子真的一直被重複呼叫,特別是我在系統中使用了多層次的類別繼承,導致呼叫次數多到一種難以想像的地步。

我試著用prototype的方式來挑戰嘗試迴避這個缺點,但是並沒有成功地找出解法。看來還是得用Dean Edwards的Base類別之類的迂迴手法才能解決這個問題吧?但是Base類別會讓Aptana看不懂,會影響到開發時候的效率,各有優劣,就看大家怎麼考量了。不過為了解決這個問題,我也想到一種「偽裝繼承」的方式來讓Base能夠用在Aptana Studio當中,下次有機會再來講講。

(more...)