BBS水木清华站∶精华区
发信人: long@eagle.ee.ntu.edu.tw (long), 看板: linux
标 题: 如何用Linuxdoc-SGML撰写并维护Linux Howto(sgml)
发信站: National Taiwan University (Sat May 18 00:46:54 1996)
转信站: maple!news.ee.nthu!news.csie.nctu!netnews.ntu!long
<!doctype linuxdoc system>
<article>
<title> 如何用Linuxdoc-SGML撰写并维护Linux Howto
<author> 吴晓龙, <tt><htmlurl url="mailto:long@eagle.ee.ntu.edu.tw" name="">long@eagle.ee.ntu.edu.tw">
<date> v1.0, 17 July 1996
<toc>
<sect>前言
<p>
最近在Linux版上大家开始讨论所谓Taiwan Linux User Group的
可能性与其发展方向,我想如果真能产生一些共识与成果,
对於Linux 以至於U*ix的推广都是一个好的起头吧.
起码每天看tw.bbs.comp.linux时可以少按几下K.......:-)
现在大家好像还在讨论阶段,对於应该致力於软体中文化还
是Howto的翻译 都还众说纷云.不过我想不管是那个方向,
文件的撰写与维护都是很重要的, 因为只有这样, 才能够
使每个人的effort不致於孤芳自赏, 也能使经验传承下来.
由於有这个想法,我就花了一点时间看了一下howto中的Writing
发现Linux的howto早就有了一致的政策与文件规格.
本土文件的政策还有赖大家讨论,不过他们的文件规格倒是
很值得我们来套用.他们是用一种叫SGML(Standard Generalized
Markup Language)来写HOWTO的,更精确地来说,他们是用这种语言
来定义HOWTO文件的结构,使得每个人都可以轻易地写出格式相同
的文件.如果有人看到这里一头雾水,还搞不清楚这是一种什麽
语言的话,没关系,我也搞不太懂这是什麽...:-)
不过这就是他的优点了,搞不懂也可以照写不误, 大家可以边写边搞,
搞搞写写.......我是说这个语言啦....:-)
它最强大的地方是可以轻松地转换成一般文字档,LaTeX(ps,dvi),
GNU Info, LyX(好像是一种WYSIWYG的LaTeX)与RTF(这我就不知道是
什麽了).也就是说,你可以专心於撰写维护一份sgml文件,而不须
将心力浪费在文件转换上.
希望藉著这份文件能够减轻documentation的负担,
而使得有更多的人开始将自己的经验与其它linuxer分享,
然後不用每天看&dquot我也要,我也是,as title&dquot的文章
然後大家能够因此有更多的心力集中在coding上,
然後....能够..世界大同,宇宙和平....:-)
<tt>本文的html版可在http://eagle.ee.ntu.edu.tw/$tilde;long/linux/simple-sgml.html存在
<sect> 安装
<sect1> 安装之前
<p>有几个package是必须的
<itemize>
<item> 安装需要
<itemize>
<item> ftp://nctuccca.edu.tw/Operating-Systems/Linux/pa
ckages/Utils/text/linuxdoc-sgml-1.5.tar.gz
<item> perl
<item> flex
<item> gcc
</itemize>
<item> Format文件需要
<itemize>
<item> groff 1.08 or 1.09
<item> TeX and LaTeX (包含CJK套件)
<item> gawk 及 GNU info tools
<item> (optional) LyX
</itemize>
</itemize>
<sect1> 安装
<p>
只需run the install script,回答binaries,library,documentation,man pages
安放之处
<sect>为了与中文big5码相容之修改
<p>假设 LINUXDOCBIN=/usr/local/bin;
LINUXDOCLIB=/usr/local/lib/linuxdoc-sgml
<em>注意:由於本人对中文码不太熟悉,
这些修改只是trial and error的结果,
无法保证所有的中文big5 code都能顺利显示,
而且修改的部份可能会造成转换後文件的特殊符号(如latex中的_,})无法显示</em>
<sect1> Script file 的修改
<p>
修改LINUXDOCBIN/sgml2txt
<p>
第17行,将COL=``no''改为COL=``no''
<p>第105行,将
latin1) cat $SGMLFILE | sed -f $LINUXDOCLIB/latin1.sed
$LINUXDOCBIN/sgmls $DASHI $SGMLDECL >
/tmp/sgml2txt$$tmp;;
改为latin1) $LINUXDOCBIN/sgmls $DASHI $SGMLDECL &d
ollar;SGMLFILE > /tmp/sgml2txt$$tmp;;
<sect1> Configuration file(LINUXDOCLIB/rep/xxx/[general,mapping])的修改
<p>
<itemize>
<item>LINUXDOCLIB/rep/latin1/general:第134行`` ''改为``$tilde;''
<item>LINUXDOCLIB/rep/latex2e/general:第120行``\_''改为``_'',
第169行``\}''改为``}''
<item>LINUXDOCLIB/rep/latex2e/mapping:
<verb>
第7行将``\\usepackage\[latin1\]{inputenc}\n''替换成``\\usepackage{CJK}\n''
第12行加入``\\begin{CJK*}{Bg5}{kai}''
第15行加入``\\end{CJK*}''
</verb>
<item>LINUXDOCLIB/rep/html/general:第128行将&nbsp换成˜
</itemize>
<sect>档案的转换
<p>
<itemize>
<item>产生文字档 <verb> sgml2txt -l xxx.sgmL </verb>
<item>产生HTML文件 <verb> sgml2html xxx.sgml </verb>
<item>产生LaTeX文件 <verb> sgml2latex -2e xxx.sgml </verb>
</itemize>
<sect>Further Information
<p>
<itemize>
<item>The QWERTZ User's Guide is available from
<tt><htmlurl url="ftp://ftp.cs.cornell.edu/pub/mdw/SGML"
name=".">ftp://ftp.cs.cornell.edu/pub/mdw/SGML">.
QWERTZ (and hence, Linuxdoc-SGML) supports many features such as
mathematical formulae, tables, figures, and so forth. I don't
recommend using most of these features in the Linux HOWTOs because
they won't render well in plain text. If you'd like to write general
documentation in SGML, I suggest using the original QWERTZ DTD instead
of the hacked-up Linuxdoc-SGML DTD, which I've modified for use
particularly by the Linux HOWTOs and other such documentation.
<item>Tom Gordon's original QWERTZ tools can be found at
<tt><htmlurl url="ftp://ftp.gmd.de/GMD/sgml"
name=".">ftp://ftp.gmd.de/GMD/sgml">.
<item>More information on SGML can be found at the following WWW
pages:
<enum>
<item><tt><url url="http://www.w3.org/hypertext/WWW/MarkUp/SGML/"
name="SGML and the Web"></tt>
<item><tt><url url="http://www.sil.org/sgml/sgml.html"
name="SGML Web Page"></tt>
</enum>
<item>James Clark's <tt/sgmls/ parser, and it's successor <tt/nsgmls/
and other tools can be found at
<tt><htmlurl url="ftp://ftp.jclark.com" name="">ftp://ftp.jclark.com">
</tt> and at <tt><url url="http://www.jclark.com"
name="James Clark's WWW Page"></tt>.
<item>You can join the Linuxdoc-SGML mailing list by sending mail to
<tt><htmlurl url="mailto:majordomo@via.ecp.fr"
name="">majordomo@via.ecp.fr"> with <tt/subscribe linuxdoc-sgml/ in
the message body. The list address is
<tt><htmlurl url="linuxdoc-mailto:sgml@via.ecp.fr"
name="linuxdoc-.">sgml@via.ecp.fr">.
<item>More information on <tt/LyX/ can be found at the
<tt><url url="http://wsiserv.informatik.uni-tuebingen.de/~ettrich/"
name="LyX WWW Page"></tt>. <tt/LyX/ is a high-level word processor
frontend to LaTeX. Quasi-WYSIWYG interface, many LaTeX styles and
layouts automatically generated. Speeds up learning LaTeX and makes
complicated layouts easy and intuitive.
</itemize>
</article>
发信人: long@eagle.ee.ntu.edu.tw (long), 看板: linux
标 题: 如何用Linuxdoc-SGML撰写并维护Linux Howto(sgml)
发信站: National Taiwan University (Sat May 18 00:46:54 1996)
转信站: maple!news.ee.nthu!news.csie.nctu!netnews.ntu!long
<!doctype linuxdoc system>
<article>
<title> 如何用Linuxdoc-SGML撰写并维护Linux Howto
<author> 吴晓龙, <tt><htmlurl url="mailto:long@eagle.ee.ntu.edu.tw" name="">long@eagle.ee.ntu.edu.tw">
<date> v1.0, 17 July 1996
<toc>
<sect>前言
<p>
最近在Linux版上大家开始讨论所谓Taiwan Linux User Group的
可能性与其发展方向,我想如果真能产生一些共识与成果,
对於Linux 以至於U*ix的推广都是一个好的起头吧.
起码每天看tw.bbs.comp.linux时可以少按几下K.......:-)
现在大家好像还在讨论阶段,对於应该致力於软体中文化还
是Howto的翻译 都还众说纷云.不过我想不管是那个方向,
文件的撰写与维护都是很重要的, 因为只有这样, 才能够
使每个人的effort不致於孤芳自赏, 也能使经验传承下来.
由於有这个想法,我就花了一点时间看了一下howto中的Writing
发现Linux的howto早就有了一致的政策与文件规格.
本土文件的政策还有赖大家讨论,不过他们的文件规格倒是
很值得我们来套用.他们是用一种叫SGML(Standard Generalized
Markup Language)来写HOWTO的,更精确地来说,他们是用这种语言
来定义HOWTO文件的结构,使得每个人都可以轻易地写出格式相同
的文件.如果有人看到这里一头雾水,还搞不清楚这是一种什麽
语言的话,没关系,我也搞不太懂这是什麽...:-)
不过这就是他的优点了,搞不懂也可以照写不误, 大家可以边写边搞,
搞搞写写.......我是说这个语言啦....:-)
它最强大的地方是可以轻松地转换成一般文字档,LaTeX(ps,dvi),
GNU Info, LyX(好像是一种WYSIWYG的LaTeX)与RTF(这我就不知道是
什麽了).也就是说,你可以专心於撰写维护一份sgml文件,而不须
将心力浪费在文件转换上.
希望藉著这份文件能够减轻documentation的负担,
而使得有更多的人开始将自己的经验与其它linuxer分享,
然後不用每天看&dquot我也要,我也是,as title&dquot的文章
然後大家能够因此有更多的心力集中在coding上,
然後....能够..世界大同,宇宙和平....:-)
<tt>本文的html版可在http://eagle.ee.ntu.edu.tw/$tilde;long/linux/simple-sgml.html存在
<sect> 安装
<sect1> 安装之前
<p>有几个package是必须的
<itemize>
<item> 安装需要
<itemize>
<item> ftp://nctuccca.edu.tw/Operating-Systems/Linux/packages/Utils/text/linuxdoc-sgml-1.5.tar.gz
<item> perl
<item> flex
<item> gcc
</itemize>
<item> Format文件需要
<itemize>
<item> groff 1.08 or 1.09
<item> TeX and LaTeX (包含CJK套件)
<item> gawk 及 GNU info tools
<item> (optional) LyX
</itemize>
</itemize>
<sect1> 安装
<p>
只需run the install script,回答binaries,library,documentation,man pages
安放之处
<sect>为了与中文big5码相容之修改
<p>假设 LINUXDOCBIN=/usr/local/bin;
LINUXDOCLIB=/usr/local/lib/linuxdoc-sgml
<em>注意:由於本人对中文码不太熟悉,
这些修改只是trial and error的结果,
无法保证所有的中文big5 code都能顺利显示,
而且修改的部份可能会造成转换後文件的特殊符号(如latex中的_,})无法显示</em>
<sect1> Script file 的修改
<p>
修改LINUXDOCBIN/sgml2txt
<p>
第17行,将COL=``no''改为COL=``no''
<p>第105行,将
latin1) cat $SGMLFILE | sed -f $LINUXDOCLIB/latin1.sed
$LINUXDOCBIN/sgmls $DASHI $SGMLDECL >
/tmp/sgml2txt$$tmp;;
改为latin1) $LINUXDOCBIN/sgmls $DASHI $SGMLDECL $SGMLFILE > /tmp/sgml2txt$$tmp;;
<sect1> Configuration file(LINUXDOCLIB/rep/xxx/[general,mapping])的修改
<p>
<itemize>
<item>LINUXDOCLIB/rep/latin1/general:第134行`` ''改为``$tilde;''
<item>LINUXDOCLIB/rep/latex2e/general:第120行``\_''改为``_'',
第169行``\}''改为``}''
<item>LINUXDOCLIB/rep/latex2e/mapping:
<verb>
第7行将``\\usepackage\[latin1\]{inputenc}\n''替换成``\\usepackage{CJK}\n''
第12行加入``\\begin{CJK*}{Bg5}{kai}''
第15行加入``\\end{CJK*}''
</verb>
<item>LINUXDOCLIB/rep/html/general:第128行将&nbsp换成˜
</itemize>
<sect>档案的转换
<p>
<itemize>
<item>产生文字档 <verb> sgml2txt -l xxx.sgmL </verb>
<item>产生HTML文件 <verb> sgml2html xxx.sgml </verb>
<item>产生LaTeX文件 <verb> sgml2latex -2e xxx.sgml </verb>
</itemize>
<sect>Further Information
<p>
<itemize>
<item>The QWERTZ User's Guide is available from
<tt><htmlurl url="ftp://ftp.cs.cornell.edu/pub/mdw/SGML"
name=".">ftp://ftp.cs.cornell.edu/pub/mdw/SGML">.
QWERTZ (and hence, Linuxdoc-SGML) supports many features such as
mathematical formulae, tables, figures, and so forth. I don't
recommend using most of these features in the Linux HOWTOs because
they won't render well in plain text. If you'd like to write general
documentation in SGML, I suggest using the original QWERTZ DTD instead
of the hacked-up Linuxdoc-SGML DTD, which I've modified for use
particularly by the Linux HOWTOs and other such documentation.
<item>Tom Gordon's original QWERTZ tools can be found at
<tt><htmlurl url="ftp://ftp.gmd.de/GMD/sgml"
name=".">ftp://ftp.gmd.de/GMD/sgml">.
<item>More information on SGML can be found at the following WWW
pages:
<enum>
<item><tt><url url="http://www.w3.org/hypertext/WWW/MarkUp/SGML/"
name="SGML and the Web"></tt>
<item><tt><url url="http://www.sil.org/sgml/sgml.html"
name="SGML Web Page"></tt>
</enum>
<item>James Clark's <tt/sgmls/ parser, and it's successor <tt/nsgmls/
and other tools can be found at
<tt><htmlurl url="ftp://ftp.jclark.com" name="">ftp://ftp.jclark.com">
</tt> and at <tt><url url="http://www.jclark.com"
name="James Clark's WWW Page"></tt>.
<item>You can join the Linuxdoc-SGML mailing list by sending mail to
<tt><htmlurl url="mailto:majordomo@via.ecp.fr"
name="">majordomo@via.ecp.fr"> with <tt/subscribe linuxdoc-sgml/ in
the message body. The list address is
<tt><htmlurl url="linuxdoc-mailto:sgml@via.ecp.fr"
name="linuxdoc-.">sgml@via.ecp.fr">.
<item>More information on <tt/LyX/ can be found at the
<tt><url url="http://wsiserv.informatik.uni-tuebingen.de/~ettrich/"
name="LyX WWW Page"></tt>. <tt/LyX/ is a high-level word processor
frontend to LaTeX. Quasi-WYSIWYG interface, many LaTeX styles and
layouts automatically generated. Speeds up learning LaTeX and makes
complicated layouts easy and intuitive.
</itemize>
</article>
BBS水木清华站∶精华区