前言

此文件為Gitit初始化生成的文件。恰巧和Gitit在Github上的說明一模一樣。

Gitit

Gitit是一個用Haskell語言撰寫而成的Wiki引擎。使用Happstack當Web serivce並且使用pandoc處理標記語言的轉換。wiki頁面和上傳的檔案可以選擇儲存在任何分散式版本控制工具中(例如git, darcs或mercurial)，而且可以使用VCS(Version Control Systems)的指令或透過wiki提供的Web界面來操作。預設情況下, 預設的標記語言是用markdown的擴充版配合pandoc的轉檔軟體，但也包含 reStructuredText、LaTeX、HTML、DocBook或Emacs Org-mode的標記方式。wiki頁面可以轉成許多不同的格式，包含LaTeX, RTF, OpenOffice ODT以及MediaWiki(一般wiki百科的那種)標記方式。設定Gitit的config可以顯示TeX math (用texmath)和標示程式碼(source code)(用highlighting-kate)。
其他功能還包括

外掛程式(plugins): dynamically loaded page transformations written in Haskell (see “Network.Gitit.Interface”)
分類(categories)
TeX math
程式碼語法標示和程式碼片段 (using highlighting-kate)
快取(caching)
支援Atom訂閱 (包含網站和每個頁面)
a library, “Network.Gitit”, that makes it simple to include a gitit wiki in any happstack application

你可以看這些功能的Demo在。

Getting 起步走(Getting started)

編譯和安裝gitit(Compiling and installing gitit)

你需要GHC編譯器和cabal-install安裝工具。GHC的載點。要注意，下載的版本必須是release 0.5、GHC 6.10或更高版本。cabal-install安裝工具必須在like unix作業系統上運作。以下是快速安裝說明。
一旦你取得了cabal-install安裝工具，安裝gitit就是最平凡小事(trivial)了：

cabal update
cabal install gitit

要安裝最新版的gitit，只要輸入這些命令。要安裝某一個版本的gitit，要從資源庫(repository)簽出(checked out)來，修改gitit的資料夾，然後再輸入:

cabal install

cabal安裝工具會自動安裝所有需要的Haskell的程式庫(libraries)。順利的話，這個過程最後會自己結束，gitit的最新版本將被安裝在你的電腦裡。cabal的資料夾。你可以用這個指令檢查:

gitit --version

如果不順利，檢查gitit是否在你local cabal-install的可執行目錄(通常是~/.cabal/bin)。並確保~/.cabal/bin設定成系統路徑。

設定支援語法標示(Optional syntax highlighting support)

If pandoc was compiled with optional syntax highlighting support, this will be available in gitit too. This feature is recommended if you plan to display source code on your wiki.
如果pandoc使用語法標示選項來編譯，同樣也可以在gitit上使用。如果你計畫在wiki上顯示原始碼，推薦使用此功能。
Highlighting support requires the pcre library, so make sure that is installed before continuing.
語法標示支援需要pcre函數庫，請在繼續之前確認已經安裝。
To install gitit with highlighting support, first ensure that pandoc is compiled with highlighting support, then install gitit as above:
在gitit安裝語法標示前，先確認pandoc是被編譯成語法標示，再依據下列指令安裝：

cabal install pandoc -fhighlighting --reinstall
cabal install gitit

執行Gitit(Running gitit)

To run gitit, you’ll need git in your system path. (Or darcs or hg, if you’re using darcs or mercurial to store the wiki data.)
在執行gitit之前，你需要確認git在作業系統路徑下。 (如果你使用 darcs或mercurial來儲存wiki的資料，確認darcs與hg在作業系統路徑下。)
Gitit assumes that the page files (stored in the git repository) are encoded as UTF-8. Even page names may be UTF-8 if the file system supports this. So you should make sure that you are using a UTF-8 locale when running gitit. (To check this, type locale.)
Gitit預設頁面檔案(儲存在git repository)是以UTF-8儲存，如果檔案系統支援以UTF-8儲存，甚至頁面名稱也是以此格式儲存。所以確認你的gitit是使用UTF-8的語言環境。(請檢查, type locale.)
Switch to the directory where you want to run gitit. This should be a directory where you have write access, since three directories, static, templates, and wikidata, and two files, gitit-users and gitit.log, will be created here. To start gitit, just type:
可以更改gitit執行目錄到你想要的位置，但必須確認你擁有寫入的權限。開始使用gitit只要輸入以下命令，就會建立包含static,templates,wikidata三個目錄，和兩個檔案gitit-users,gitit.log

gitit

If all goes well, gitit will do the following:
如果一切順利，這個指令會執行下列動作：

Create a git repository, wikidata, and add a default front page.
Create a static directory containing files to be treated as static files by gitit.
Create a templates directory containing HStringTemplate templates for wiki pages.
Start a web server on port 5001.
建立一個git的儲存庫wikidata, 和增加一個預設的頁面.
建立一個static目錄，包含一些初始化檔案.
建立一個templates目錄，包含 HStringTemplate templates給各個頁面.
在連接埠5001啟動一個 Web Server.

Check that it worked: open a web browser and go to http://localhost:5001.
開啟瀏覽器輸入確認是否正常運作.
You can control the port that gitit runs on using the -p option: gitit -p 4000 will start gitit on port 4000. Additional runtime options are described by gitit -h.
你可以使用 -p 選項，例如:gitit -p 4000 將更改連接埠至 4000。最後你可以在執行時使用gitit -h取得說明。

使用Gitit(Using gitit)

Wiki連結和撰寫語法(Wiki links and formatting)

For instructions on editing pages and creating links, see the “Help” page.
有關編輯頁面和創建連結的說明，請參閱“幫助”頁面。
Gitit interprets links with empty URLs as wikilinks. Thus, in markdown pages, [Front Page]() creates an internal wikilink to the page Front Page. In reStructuredText pages, `Front Page <>`_ has the same effect.
Gitit 會將空的連結當作是 wikilinks，進而建立一個新頁面。 [Front Page]() 會建立一個內部的 wikilink 到 Front Page. 在 reStructuredText 頁面使用 `Front Page <>`_ 有相同效果。
If you want to link to a directory listing for a subdirectory, use a trailing slash: [foo/bar/]() creates a link to the directory for foo/bar.
如果你想要一個連結清單到根目錄，可以使用下列語法，來建一個連結到foo/bar目錄： [foo/bar/]()

頁面後設資料(Page metadata)

在頁面開頭可以加入後設資料_非必要。範例如下：

---
format: latex+lhs
categories: haskell math
toc: no
title: Haskell and
  Category Theory
...

\section{Why Category Theory?}

後設資料由key-value列表組成，每一行為單獨的key-value。如果需要key可以用空白隔開連接多個key'。(這裡有一個插圖標頭的範例)後設資料第一行必須以—為開頭，並且最後必須以…或一個以上的空白行為結束。(後設資料是有效的非標記式語言[(YAML)](http://zh.wikipedia.org/wiki/YAML)文件, 雖然不是所有非標記式語言`文件在後設資料都是有效的)
後設資料目前支援的key如下:

format: 指定顯示此頁以何種語法解讀
允許的值是 markdown、rst、latex、html、markdown+lhs、
rst+lhs、latex+lhs。(忽略大小寫，所以你也可以寫成LaTeX、HTML…等)
設定+lhs意思是，如果另一個語法出問題，該文章就當作Haskell來顯示。
categories: 頁面標籤，可以在左列的分類索引(categories)中新增徢徑。
toc: 變更configuration檔設定的table-of-contents; 簡單的說，就是設定每一頁的大綱是否顯示; 值可以設定成yes、no或true、false (忽略大小寫)。
title: 替代原本的文件名稱當文章標題。(預設的文章標題，就是檔案名稱)

標記程式碼(Highlighted source code)

如果編譯gitit針對一個已經有支援標示程式碼的Pandoc版本 (see above)，你可以界定程式碼區塊(delimited code blocks)來標示程式碼語法:

~~~ {.haskell .numberLines}
qsort []     = []
qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++
               qsort (filter (>= x) xs) 
~~~

用下面的指令可以看到你編譯的Pandoc支持了什麼的語言的標示

pandoc -v

設定和個人化Gitit(Configuring and customizing gitit)

設定選項(Configuration options)

使用這個參數 -f [filename] 指定config設定檔:

gitit -f my.conf

如果不使用這個選項，gitit會使用預設的config設定。為了取得你可以輸入下面的指令取得目前gitit的預設config的副本:

gitit --print-default-config > my.conf

預設的config檔是有經過註解的文件。

`static`資料夾(The `static` directory)

若收到一個request訊息，gitit總是會先找static資料夾裡的資料(或任何在static-dir的檔案(configuration file))如果找到檔案對應到即將要顯示的資料，就會馬上送出。如果在static找不到的檔案, gitit接下來會依據static子目錄($CABALDIR/share/gitit-x.y.z/data)裡的gitit資料檔。這是儲存預設css、javascripts和圖檔的地方。如果文件沒有找到，gitit會將它視為wiki頁面或wiki的執行指令。
So, you can throw anything you want to be served statically (for example, a robots.txt file or favicon.ico) in the static directory. You can override any of gitit’s default css, javascript, or image files by putting a file with the same relative path in static. Note that gitit has a default robots.txt file that excludes all URLs beginning with /_.
Note: if you set static-dir to be a subdirectory of repository-path, and then add the files in the static directory to your repository, you can ensure that others who clone your wiki repository get these files as well. It will not be possible to modify these files using the web interface, but they will be modifiable via git.

使用git以外的版本控制系統(Using a VCS other than git)

By default, gitit will store wiki pages in a git repository in the wikidata directory. If you’d prefer to use darcs instead of git, you need to add the following field to the configuration file:

repository-type: Darcs

If you’d prefer to use mercurial, add:

repository-type: Mercurial

This program may be called “darcsit” instead of “gitit” when a darcs backend is used.
Note: we recommend that you use gitit/darcsit with darcs version 2.3.0 or greater. If you must use an older version of darcs, then you need to compile the filestore library without the (default) maxcount flag, before (re)installing gitit:

cabal install --reinstall filestore -f-maxcount
cabal install --reinstall gitit

Otherwise you will get an error when you attempt to access your repository.

變更佈景主題(Changing the theme)

改變wiki頁面的排版，只要修改在static/css的custom.css。
改變列印頁面的排版，取得一份gitit的預設print.css到static/css，並且修改它。
想要換掉logo圖的話，可以找一張.png檔，替換掉static/img/logo.png即可。預設大小為138×155 pixels。
想要修改註腳(footer)的話，修改 templates/footer.st。
如果想要修改更多的話，可以重寫預設模版(template)，在$CABALDIR/share/gitit-x.y.z/data/templates可以找到，再放到templates資料夾中，就會以此模版為顯示模版。其中page.st是主幹模版(master template)；由它來引用其它的模版。模版內使用的變數，用$
Interpolated variables are surrounded by $s, so literal $ must be backslash-escaped.

增加數學支援(Adding support for math)

To write math on a markdown-formatted wiki page, just enclose it in dollar signs, as in LaTeX:

Here is a formula:  $\frac{1}{\sqrt{c^2}}$

You can write display math by enclosing it in double dollar signs:

$$\frac{1}{\sqrt{c^2}}$$

Gitit can display TeX math in three different ways, depending on the setting of math in the configuration file:

mathml (default): Math will be converted to MathML using texmath. This method works with IE+mathplayer, Firefox, and Opera, but not Safari.
jsMath: Math will be rendered using the jsMath javascript. If you want to use this method, download jsMath and jsMath Image Fonts from the jsMath download page. You’ll have two .zip archives. Unzip them both in the static/js directory (a new subdirectory, jsMath, will be created). This works with all browsers, but is slower and not as nice looking as MathML.
raw: Math will be rendered as raw LaTeX codes.

限制存取(Restricting access)

If you want to limit account creation on your wiki, the easiest way to do this is to provide an access-question in your configuration file. (See the commented default configuration file.) Nobody will be able to create an account without knowing the answer to the access question.
如果你想要限制建立帳號的權限，最簡單的方式是提供access-question在你的設定檔案。 (請參閱預設的設定檔案解說)
在不知道access-question的答案下，就無法建立帳號。
Another approach is to use HTTP authentication. (See the config file comments on authentication-method.)
另一種方法是使用HTTP認證。（請參閱配置文件中的註釋上authentication-method）

外掛程式(Plugins)

Plugins are small Haskell programs that transform a wiki page after it has been converted from Markdown or RST. See the example plugins in the plugins directory. To enable a plugin, include the path to the plugin (or its module name) in the plugins field of the configuration file. (If the plugin name starts with Network.Gitit.Plugin., gitit will assume that the plugin is an installed module and will not look for a source file.)
Plugin support is enabled by default. However, plugin support makes the gitit executable considerably larger and more memory-hungry. If you don’t need plugins, you may want to compile gitit without plugin support. To do this, unset the plugins Cabal flag:

cabal install --reinstall gitit -f-plugins

Note also that if you compile gitit for executable profiling, attempts to load plugins will result in “internal error: PAP object entered!”

透過Git存取wiki (Accessing the wiki through git)

All the pages and uploaded files are stored in a git repository. By default, this lives in the wikidata directory (though this can be changed through configuration options). So you can interact with the wiki using git command line tools:
所有頁面和上傳的檔案被儲存在 git repository. 預設放在wikidata目錄底下 (當然這可以透過設定檔案更改). 所以你可以使用 git 命令工具操作 wiki:

git clone ssh://my.server.edu/path/of/wiki/wikidata
cd wikidata
vim Front\ Page.page  # edit the page
git commit -m "Added message about wiki etiquette" Front\ Page.page
git push

If you now look at the Front Page on the wiki, you should see your changes reflected there. Note that the pages all have the extension .page.
現在回到Front Page, 可以看到剛剛所做的更改. 每個頁面都有對應的.page頁面。
If you are using the darcs or mercurial backend, the commands will be slightly different. See the documentation for your VCS for details.
如果你使用 darcs 或 mercurial 為後端，命令會有些不同。請參考相關的 VCS 詳細說明.

性能(Performance)

Caching

By default, gitit does not cache content. If your wiki receives a lot of traffic or contains pages that are slow to render, you may want to activate caching. To do this, set the configuration option use-cache to yes. By default, rendered pages, highlighted source files, and exported PDFs will be cached in the cache directory. (Another directory can be specified by setting the cache-dir configuration option.)
Cached pages are updated when pages are modified using the web interface. They are not updated when pages are modified directly through git or darcs. However, the cache can be refreshed manually by pressing Ctrl-R when viewing a page, or by sending an HTTP GET or POST request to /_expire/path/to/page, where path/to/page is the name of the page to be expired.
Users who frequently update pages using git or darcs may wish to add a hook to the repository that makes the appropriate HTTP request to expire pages when they are updated. To facilitate such hooks, the gitit cabal package includes an executable expireGititCache. Assuming you are running gitit at port 5001 on localhost, and the environment variable CHANGED_FILES contains a list of the files that have changed, you can expire their cached versions using

expireGititCache http://localhost:5001 $CHANGED_FILES

Or you can specify the files directly:

expireGititCache http://localhost:5001 "Front Page.page" foo/bar/baz.c

This program will return a success status (0) if the page has been successfully expired (or if it was never cached in the first place), and a failure status (> 0) otherwise.
The cache is persistent through restarts of gitit. To expire all cached pages, simply remove the cache directory.

Idle

By default, GHC’s runtime will repeatedly attempt to collect garbage when an executable like Gitit is idle. This means that gitit will, after the first page request, never use 0% CPU time and sleep, but will use ~1%. This can be bad for battery life, among other things.
To fix this, one can disable the idle-time GC with the runtime flag -I0:

gitit -f my.conf +RTS -I0 -RTS

在Gitit使用Apache(Using gitit with apache)

Most users who run a public-facing gitit will want gitit to appear at a nice URL like http://wiki.mysite.com or http://mysite.com/wiki rather than http://mysite.com:5001. This can be achieved using apache’s mod_proxy.

Proxying to `http://wiki.mysite.com`

Set up your DNS so that http://wiki.mysite.com maps to your server’s IP address. Make sure that the mod_proxy module is loaded, and set up a virtual host with the following configuration:

<VirtualHost *>
    ServerName wiki.mysite.com
    DocumentRoot /var/www/
    RewriteEngine On
    ProxyPreserveHost On
    ProxyRequests Off

    <Proxy *>
       Order deny,allow
       Allow from all
    </Proxy>

    ProxyPassReverse /    http://127.0.0.1:5001
    RewriteRule ^(.*) http://127.0.0.1:5001$1 [P]

    ErrorLog /var/log/apache2/error.log
    LogLevel warn

    CustomLog /var/log/apache2/access.log combined
    ServerSignature On

</VirtualHost>

Reload your apache configuration and you should be all set.

Using nginx to achieve the same

Drop a file called wiki.example.com.conf into /etc/nginx/conf.d (or where ever your distribution puts it).

server {
    listen 80;
    server_name wiki.example.com
    location / {
        proxy_pass        http://127.0.0.1:5001/;
        proxy_set_header  X-Real-IP  $remote_addr;
        proxy_redirect off;
    }
    access_log /var/log/nginx/wiki.example.com.log main;
}

Reload your nginx config and you should be all set.

Proxying to `http://mysite.com/wiki`

Make sure the mod_proxy, mod_headers, mod_proxy_http, and mod_proxy_html modules are loaded. mod_proxy_html is an external module, which can be obtained here (http://apache.webthing.com/mod_proxy_html/). It rewrites URLs that occur in web pages. Here we will use it to rewrite gitit’s links so that they all begin with /wiki/.
First, tell gitit not to compress pages, since mod_proxy_html needs uncompressed pages to parse. You can do this by setting the gitit configuration option

compress-responses: no

Second, modify the link in the reset-password-message in the configuration file: instead of

http://$hostname$:$port$$resetlink$

set it to

http://$hostname$/wiki$resetlink$

Restart gitit.
Now add the following lines to the apache configuration file for the mysite.com server:

# These commands will proxy /wiki/ to port 5001

ProxyRequests Off

<Proxy *>
  Order deny,allow
  Allow from all
</Proxy>

ProxyPass /wiki/ http://127.0.0.1:5001/

<Location /wiki/>
  SetOutputFilter  proxy-html
  ProxyPassReverse /
  ProxyHTMLURLMap  /   /wiki/
  RequestHeader unset Accept-Encoding
</Location>

Reload your apache configuration and you should be set.
For further information on the use of mod_proxy_http to rewrite URLs, see the mod_proxy_html guide.

Using gitit as a library

By importing the module Network.Gitit, you can include a gitit wiki (or several of them) in another happstack application. There are some simple examples in the haddock documentation for Network.Gitit.

回報bug(Reporting bugs)

Bugs may be reported (and feature requests filed) at http://code.google.com/p/gitit/issues/list.
There is a mailing list for users and developers at http://groups.google.com/group/gitit-discuss.

致謝(Acknowledgements)

A number of people have contributed patches:

Gwern Branwen helped to optimize gitit and wrote the InterwikiPlugin. He also helped with the Feed module.
Simon Michael contributed the patch adding RST support.
Henry Laxen added support for password resets and helped with the apache proxy instructions.
Anton van Straaten made the process of page generation more modular by adding Gitit.ContentTransformer.
Robin Green helped improve the plugin API and interface, and fixed a security problem with the reset password code.
Thomas Hartman helped improve the index page, making directory browsing persistent, and fixed a bug in template recompilation.
Justin Bogner improved the appearance of the preview button.
Kohei Ozaki contributed the ImgTexPlugin.
Michael Terepeta improved validation of change descriptions.
mightybyte suggested making gitit available as a library, and contributed a patch to ifLoggedIn that was needed to make gitit usable with a custom authentication scheme.

I am especially grateful to the darcs team for using darcsit for their public-facing wiki. This has helped immensely in identifying issues and improving performance.
Gitit’s default visual layout is shamelessly borrowed from Wikipedia. The stylesheets are influenced by Wikipedia’s stylesheets and by the bluetrip CSS framework (see BLUETRIP-LICENSE). Some of the icons in img/icons come from bluetrip as well.

《DarkBlack》

自己動手架設wiki(10) - 系統初始化生成的「使用者手冊」

前言

Gitit

Getting 起步走(Getting started)

編譯和安裝gitit(Compiling and installing gitit)

設定支援語法標示(Optional syntax highlighting support)

執行Gitit(Running gitit)

使用Gitit(Using gitit)

Wiki連結和撰寫語法(Wiki links and formatting)

頁面後設資料(Page metadata)

標記程式碼(Highlighted source code)

設定和個人化Gitit(Configuring and customizing gitit)

設定選項(Configuration options)

`static`資料夾(The `static` directory)

使用git以外的版本控制系統(Using a VCS other than git)

變更佈景主題(Changing the theme)

增加數學支援(Adding support for math)

限制存取(Restricting access)

外掛程式(Plugins)

透過Git存取wiki (Accessing the wiki through git)

性能(Performance)

Caching

Idle

在Gitit使用Apache(Using gitit with apache)

Proxying to `http://wiki.mysite.com`

Using nginx to achieve the same

Proxying to `http://mysite.com/wiki`

Using gitit as a library

回報bug(Reporting bugs)

致謝(Acknowledgements)

沒有留言:

張貼留言

我的最愛

誰擁有網誌

關鍵字文章

來踩過的腳印數

自己動手架設wiki(10) - 系統初始化生成的「使用者手冊」

前言

Gitit

Getting 起步走(Getting started)

編譯和安裝gitit(Compiling and installing gitit)

設定支援語法標示(Optional syntax highlighting support)

執行Gitit(Running gitit)

使用Gitit(Using gitit)

Wiki連結和撰寫語法(Wiki links and formatting)

頁面後設資料(Page metadata)

標記程式碼(Highlighted source code)

設定和個人化Gitit(Configuring and customizing gitit)

設定選項(Configuration options)

static資料夾(The static directory)

使用git以外的版本控制系統(Using a VCS other than git)

變更佈景主題(Changing the theme)

增加數學支援(Adding support for math)

限制存取(Restricting access)

外掛程式(Plugins)

透過Git存取wiki (Accessing the wiki through git)

性能(Performance)

Caching

Idle

在Gitit使用Apache(Using gitit with apache)

Proxying to http://wiki.mysite.com

Using nginx to achieve the same

Proxying to http://mysite.com/wiki

Using gitit as a library

回報bug(Reporting bugs)

致謝(Acknowledgements)

沒有留言:

張貼留言

我的最愛

誰擁有網誌

關鍵字文章

來踩過的腳印數

`static`資料夾(The `static` directory)

Proxying to `http://wiki.mysite.com`

Proxying to `http://mysite.com/wiki`