Do not use Edit(GUI) button.
?TableOfContents(4)
Copyright 2007, 2008 Osamu Aoki GPL, (Please agree to GPL, GPL2, and any version of GPL which is compatible with DSFG if you update any part of wiki page)
Guide for contributing to Debian Reference
Debian Reference upstream source is http://wiki.debian.org/DebianReference .
Rules
Here are the rules.
Do not use Edit(GUI) button of MoinMoin.
- You can update anytime for:
- grammar errors
- spelling errors
- moved URL location
- package name transition adjustment (emacs23 etc.)
- clearly broken script.
- Before updating real contents:
You have to discuss it on debian-doc@lists.debian.org (1 week wait for response please)
- You have to read the whole document to avoid duplication.
- Follow the existing style.
- Make sure you are reachable via e-mail.
- Think twice before doing anything.
- Do your own research on the latest Debian system by experimenting.
- Make contents as generic suitable for slow content update cycle (including future translation work).
- It is usually good to place only the pointer to the original information.
- Even if new contents are required, please shorten the description to half its original draft length.
Make alternative page proposals as wiki and post message to debian-doc@lists.debian.org
I use this moinmoin platform for its ability for table and XML export.
This wiki will be post-processed by XSLT/XML tools and should be written accordingly:
- The content in the index section at the top of each wiki page will be dropped when converted to XML.
@ { @ tag @ } @ (without spaces between @s) markup on wiki pages is converted to an internal link.
- Do not use overly fancy wiki features not supported by XML conversion backend, available from the git repo. (Your help to remove fancy features in moinmoin is welcome.)
- Do not make a complicated table with connected cells spanning rows or columns.
Do not use FootNote nor face marks such as :) for .
- Follow the wiki style:
- The codenames are always in the lower case (sid, etch, lenny, ...)
Indent only for * and 1. -started lines, one space per level of nesting.
Do not indent lines started with : ||, { { { (without spaces).
Some graphic marks such as /!\ for are converted to marking for para. (See test page.)
- Do not indent for lines started with these graphic marks.
- Wiki table markup is processed in special ways:
The first line of a table is used as: <title> [, package column, popcon column].
- popcon and package sizes are autogenerated by a script if specified in the first line. (Values in wiki are ignored)
The second line of a table is used as: <thead>.
@ @ @tag@ @ @ (without spaces between @s) in wiki are converted to &tag; in XML.
- The final tag contents in HTML is determined by the HTML generation script.
- All internal wiki links will be removed when converted to XML.
- For the same text with URL link, external URL link should match if it repeats.
- one word reference should chose mostly wikipedia
No % or & usage in URL address reference until I fix moin2urls.xsl.
- Try to keep contents in
... commands examples ...
- language neutral so translation will not affect them.
- Do not bloat this document.
- It is already getting too big for me (osamu) to maintain .
- If you want to make an XML document for a particular topic from the wiki, please use the code I use and start a new document. (GPL).
This ensures (eventually) clean conversion to DocBook XML and makes my work easy.
If funny things happen, look for single quote repeats, etc. in wiki source.
Code sections marked as "{ { { \n } } }" without using spaces will cause XML export errors; thus, always use spaces around \n.
List export has <para> markup bugs; after conversion, review and correct them, please.
This Wiki page to Docbook conversion examples step-by-step:
[http://people.debian.org/~osamu/pub/getwiki/en/test-all.en.xml Docbook XML parent]
[http://people.debian.org/~osamu/pub/getwiki/en/test.en.xml Docbook XML child]
[http://people.debian.org/~osamu/pub/getwiki/html/test-one.en.html HTML from Docbook]
[http://people.debian.org/~osamu/pub/dr2.tar.bz2 HTML build system] - slightly old snapshot
Hints for tools to help updating this document
Public server: http://wiki.debian.org/DebianReference
You create your own mirror: http://localhost/Wiki/DebianReference
- See Makefile and use targets: diff gedit ...
Interesting info found by googling
[http://www.kernel.org/pub/software/scm/git/docs/cvs-migration.html git for CVS users]
[http://live.gnome.org/GitForGnomeDevelopers Git for GNOME developers]
[http://www.mantisbt.org/wiki/doku.php/mantisbt:git_svn Using Git with SVN]
[http://andy.delcambre.com/2008/3/4/git-svn-workflow Git SVN Workflow]
[http://www.gnome.org/~federico/misc/git-cheat-sheet.txt GIT for mortals]
[http://kerneltrap.org/mailarchive/git/2007/6/26/250068 GIT + CVS workflow query]
Fonts on the Debian system
This is based on system just around lenny release.
Here is a list of references for fonts on the Debian system.
[http://en.wikipedia.org/wiki/Computer_font Computer font]
[http://www.faqs.org/faqs/fonts-faq/part15/ comp.fonts FAQ: X11 Info]
[http://fontforge.sourceforge.net/bibliography.html ?FontForge bibliography]
[http://www.suse.de/~mfabian/suse-cjk/fonts.html SUSE CJK Fonts]
[http://wiki.debian.org/Fonts/Defoma Defoma and Debian font system]
[http://unifont.org/iuc27/index.html The Penguin and Unicode: The State of Unicode and Internationalization in Linux]
The fonts in the X window
The defoma package, which stands for "DEbian FOnt MAnager", provides a framework for automatic font configuration including X.
The aptitude will help you find required font easily
by the short package list under "Packages which depend on defoma" under the defoma package list,
by the short package list under "Tasks" -> "Localization",
by the filtered flat package list of font data with regex on debtag: "~Gmade-of::data:font",
by the filtered flat package list of the BDF (bitmap) font packages with regex on package name: "~nxfonts-", or
by the filtered flat package list of the TrueType (outline) font packages with regex on package name: "~nttf-".
The standard xfs in the X server works fine with TrueType fonts.
Since Free fonts are sometimes limited, installing or sharing some commercial TrueType fonts is an option for a Debian users. In order to make this process easy for the user, some convenience packages have been created:
ttf-mathematica4.1
ttf-mscorefonts-installer
You'll have a really good selection of TrueType fonts at the expense of contaminating your Free system with non-Free fonts.
All these font packages in Debian should work without any efforts and appear available to all X programs that use the regular "core" font system. This includes things like Xterm, Emacs, and most other non-KDE and non-GNOME applications.
Basic fonts
There are 2 major types of [http://en.wikipedia.org/wiki/Computer_font computer fonts]:
- bitmap fonts (good for low resolution rasterization)
- outline/stroke fonts (good for high resolution rasterization)
While scaling of bitmap fonts causes jugged image, scaling of outline/stroke fonts produces smooth image.
Bitmap fonts on the Debian system are provided by [http://fontforge.sourceforge.net/pcf-format.html X11 pcf bitmap font files] having their file extension ".pcf".
Outline fonts on the Debian system are provided by:
[http://en.wikipedia.org/wiki/PostScript ?PostScript] Type 1 font files having their file extension ".pfb" (binary font file) and ".afm" (font metrics file).
[http://en.wikipedia.org/wiki/TrueType TrueType] font files having their file extension ".ttf".
Table of corresponding [http://en.wikipedia.org/wiki/PostScript ?PostScript] Type 1 fonts. |
1 |
2 |
3 |
|
|
|
font package |
popcon |
size |
sans-serif font |
serif font |
monospace font |
source of font |
(?PostScript) |
|
|
Helvetica |
Times |
Courier |
Adobe |
gsfonts |
|
|
Nimbus Sans L |
Nimbus Roman No9 L |
Nimbus Mono L |
[http://en.wikipedia.org/wiki/URW URW] (Adobe compatible size) |
gsfonts-x11 |
|
|
Nimbus Sans L |
Nimbus Roman No9 L |
Nimbus Mono L |
X font support with ?PostScript Type 1 fonts. |
t1-cyrillic |
|
|
Free Helvetian |
Free Times |
Free Courier |
URW extended (Adobe compatible size) |
lmodern |
|
|
LMSans* |
LMRoman* |
LMTypewriter* |
scalable ?PostScript and ?OpenType fonts based on Computer Modern (from TeX) |
Table of corresponding [http://en.wikipedia.org/wiki/TrueType TrueType] fonts. |
1 |
2 |
3 |
|
|
|
font package |
popcon |
size |
sans-serif font |
serif font |
monospace font |
source of font |
ttf-mscorefonts-installer |
|
|
[http://en.wikipedia.org/wiki/Times_New_Roman Times New Roman] |
[http://en.wikipedia.org/wiki/Courier_(typeface) Courier New] |
Microsoft (Adobe compatible size) |
|
ttf-liberation |
|
|
Liberation Sans |
Liberation Serif |
Liberation Mono |
[http://en.wikipedia.org/wiki/Liberation_fonts Liberation Fonts project] (Microsoft compatible size) |
ttf-freefont |
|
|
?FreeSans |
?FreeSerif |
?FreeMono |
[http://savannah.gnu.org/projects/freefont/ GNU freefont] (Microsoft compatible size) |
ttf-bitstream-vera |
|
|
Bitstream Vera Sans |
Bitstream Vera Serif |
Bitstream Vera Sans Mono |
[http://www.gnome.org/fonts/ Bitstream, Inc.] |
ttf-dejavu |
|
|
?DejaVu Sans |
?DejaVu Serif |
?DejaVu Sans Mono |
[http://dejavu.sourceforge.net/], Bitstream extended code support |
ttf-dejavu-core |
|
|
?DejaVu Sans |
?DejaVu Serif |
?DejaVu Sans Mono |
[http://dejavu.sourceforge.net/] basic font variants |
ttf-dejavu-extra |
|
|
?DejaVu Sans |
?DejaVu Serif |
?DejaVu Sans Mono |
[http://dejavu.sourceforge.net/] extra font vaiants |
ttf-unifont |
|
|
N/A |
N/A |
unifont |
[http://Unifoundry.com], GNU Unifont cover all code |
CJK fonts
To provide [http://unifont.org/ complete information about Unicode fonts, Unicode-enabled software, internationalization, and Unicode usability issues] on [http://en.wikipedia.org/wiki/Free_and_open_source_software free/libre/open source (FLOSS)] operating systems is beyond the scope of this document. Here are some key points mostly focused on CJK issues.
Table of key words used in CJK font names. |
|
|
|
font type |
Japanese font |
Chinese font |
Korean font |
sans-serif |
gothic, ゴチック |
hei, gothic |
dodum, gulim, gothic |
serif |
mincho, 明朝 |
song, ming |
batang |
Usually, font name with "P" is proportional fonts.
Double width: e.g., in Shift_JIS code table comprises 7070 characters:
- JIS X 0201 single-byte characters (191 characters),
- JIS X 0208 double-byte characters (6879 characters).
double-byte characters occupy double width on console terminals.
In order to cope with special needs of CJK, there are some special fonts and supporting files.
For fixed fonts covering single-byte and double-byte characters, [http://www.ibiblio.org/pub/packages/ccic/software/info/HBF-1.1/ Hanzi Bitmap Font (HBF) File] with file extension ".hbf" is used.
In order to save space for [http://en.wikipedia.org/wiki/TrueType TrueType] font files, [http://en.wikipedia.org/wiki/TrueType TrueType] font collection file is used.
I order to cover complicated code space of characters, CID keyed Type 1 [http://en.wikipedia.org/wiki/PostScript ?PostScript] font is used with CMap files starting themselves with "%!PS-Adobe-3.0 Resource-CMap".
Font configuration and rendering
All these fonts described above (@{@basicfonts@}@, @{@cjkfonts@}@) are equally supported for displaying and printing using "libfreetype6", "libxft2", "ghostscript" and "fontconfig" packages on the Debian system.
Table of packages to support displaying and printing of fonts. |
1 |
2 |
3 |
package |
popcon |
size |
description |
libfreetype6 |
|
|
[http://freetype.sourceforge.net/index.html ?FreeType] 2 font engine, shared library files |
fontconfig |
|
|
[http://en.wikipedia.org/wiki/Fontconfig generic font configuration library] - support binaries |
fontconfig-config |
|
|
generic font configuration library - configuration |
defoma |
|
|
Debian Font Manager -- automatic font configuration framework |
ghostscript |
|
|
[http://en.wikipedia.org/wiki/Ghostscript The GPL Ghostscript PostScript/PDF interpreter] |
ghostscript-x |
|
|
The GPL Ghostscript PostScript/PDF interpreter - X Display support |
libxft2 |
|
|
?FreeType-based font drawing library for X |
x-ttcidfont-conf |
|
|
TrueType and CID fonts configuration for X (for CJK support) |
libpoppler3 |
|
|
PDF rendering library |
poppler-data |
|
|
Encoding data for the poppler PDF rendering library (for CJK support) |
cmap-adobe-cns1 |
|
|
CMaps for Adobe-CNS1 (for traditional Chinese support) |
cmap-adobe-gb1 |
|
|
CMaps for Adobe-GB1 (for simplified Chinese support) |
cmap-adobe-japan1 |
|
|
CMaps for Adobe-Japan1 (for Japanese standard support) |
cmap-adobe-japan2 |
|
|
CMaps for Adobe-Japan2 (for Japanese extra support) |
cmap-adobe-korea1 |
|
|
CMaps for Adobe-Korea1 (for Korean support) |
Font path check method
"xset q" X font path
"ghostscript -h" gohstscript font path
"fc-match" fontconfig font default
Examples
This section contains examples and scratch pad contents.
Table
Always assumes the first line is <title>, the second line is <thead> and the rest lines are <tbody> <row>s. (hello)
Example of table 1 |
|
TITLE1 |
TITLE2 |
DATA 11 |
DATA 12 |
DATA 21 |
DATA 22 |
Special paragraphs
Here are examples of Wiki marking used.
/!\ for "Warning" (alert)
<!> for "Caution" (attention)
{*} for "Important" (star_on)
{i} for "Tip" (icon-info)
(!) for "Note" (idea)
{OK} for "Note" (thumbs-up)
(./) for "Note" (check-mark)
Line foldings
line1 starting line break examples line2 w/o space from previous line
line3 w 1 line space from previous line
line2 w 2 space from previous line
line2 w 3 space from previous line line with ampersand & &
Data for popcon data and package size
The following packages are referred in the main text.
List of packages whose popcon and/or package size were referred in the main text |
1 |
2 |
3 |
package |
popcon |
package size |
dummy |
gksu |
- |
- |
- |
screen |
- |
- |
- |
rutebook |
- |
- |
- |
See http://wiki.debian.org/UTF8BrokenApps
Escape confusion
MoinMoin conversion bug for " \n " needs to be worked around by placing space around it.
internal links
can be referred as @{@internallinks@}@ which will create correct reference in HTML.
- All characters converted to lower cases.
- 0-9 converted to a-j
- Drop all special characters and spaces.
- For longer reference name, it trim center parts and make it first and last 16 characters each.
- See HTML link name as quick check after generation.
Do not use " [[Anchor(internalLinks)]] " for now in the main text used by building final HTML files. (It may be a good idea but you need to do it for entire document.)
The normal anchor feature of MoinMoin wiki is not supported by the XML conversion tool now.