www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - halitbut Lightweight markup language, txt input, output

reply yidabu <yidabu.nospam gmail.com> writes:
I found a good Lightweight markup language, called halitbut (Author Simon
Tatham):
home: 
http://www.chiark.greenend.org.uk/~sgtatham/halibut/

It's useful for D programming lanuge DOC, I want to build a halitbut.lib for D
on Windows, but I'm newbie of C language, any one help me to build a
halitbut.lib ?


From halitbut home:
Halibut is a documentation production system, with elements similar to TeX,
debiandoc-sgml, TeXinfo, and others. It is primarily targeted at people
producing software manuals. 

What does it do?
Halibut reads documentation source in a single input format, and produces
multiple output formats containing the same text. The supported output formats
are: 

Plain ASCII text 
HTML 
PDF 
PostScript 
Unix man pages 
Unix info, generated directly as .info files rather than .texi sources 
Windows HTML Help (.CHM files), or rather source which can be fed to the MS
HTML Help compiler to generate them 
Windows WinHelp (old-style .HLP files), generated directly without needing a
help compiler. 
Other notable features include: 

...
A common question is why I had to write a new documentation system rather than
using an existing one. 

TeX is fundamentally geared towards typesetting on to a printed page, so it
didn't seem feasible to get it to output any of the more markup-oriented
formats such as man pages and Windows Help. 

TeXinfo can generate both printed manuals and on-line help, but neither one is
very pretty IMO; and the on-line help output is limited to info format, which I
didn't fancy post-processing into Windows Help, HTML etc. 

debiandoc-sgml generates a good range of file formats, suggesting that it would
probably not have been too hard to hack in a couple more; but when I looked at
it I didn't see indexing support at anything like the level I wanted. Indexing
is a big and tricky task, and I would hate to hack index support into a
document producer after it was written; better to design it in from scratch. 

DocBook wasn't well known enough for me to have heard of it when this project
started. When it was later brought to my attention, I looked at the DocBook
input format and simply didn't like it. For a start, it just involved too much
typing for my taste: all the keywords are far too long (<appendix> rather than
\A, for example), and the SGML/XML syntax requires you to type each keyword
again when you close the section. I just prefer the TeX-like
backslash-and-braces markup syntax to the HTMLish angle-brackets-and-slashes
one. I was also suspicious of DocBook's very detailed semantic markup such as
individually annotating things like people's names; I find writing manuals hard
enough work as it is, without having to write as much metadata as text.
Perhaps, if anyone asks for it, I might consider writing a DocBook output
format for Halibut, so that Halibut input can be conveniently translated into
DocBook format. 

Where did this crazy idea come from?
This crazy idea came to me while I was working on NASM, and wanted the
documentation to be available on the project's web site as well as in printable
and online-viewable formats. I hacked together a Perl implementation of most of
the Halibut concepts, without any real design, and it worked well enough to get
the NASM manual off the ground. 

However, the Perl version (which is still distributed in the current NASM
archive as far as I know) had serious limitations, most noticeably that it was
extremely slow. Also the code was very hard to maintain (largely because I
wrote a lot of the parser as line-noise regexps), the index management had some
good ideas but implemented them in fundamentally broken ways ¡­ It just didn't
seem sensible to continue trying to put features into it. So I rewrote it from
the ground up in portable C, learning from all my mistakes in the original Perl
version (¡®build one to throw away¡¯). 

Why on earth ¡®Halibut¡¯? What relevance does the name have to anything?
Historical reasons. It's probably better not to ask. 

What is its current status?
Halibut 1.0 was released on 2007-01-31, and supports all of the features
described above. 

You can download the release source code here [halibut-1.0.tar.gz], or you can
read the release documentation online in HTML, PDF or plain text. 

Alternatively, if you want to keep up to date with the very latest development,
you can check the development sources out from our Subversion repository. The
Subversion URL you need for the Halibut trunk development is
svn://svn.tartarus.org/sgt/halibut. You will also need the character-set
handling library, which Halibut will expect to be checked out alongside the
main Halibut source. So you could check out all the code necessary for the
trunk version of Halibut using a pair of commands such as 

svn co svn://svn.tartarus.org/sgt/halibut
svn co svn://svn.tartarus.org/sgt/charset
To check out branches or release tags of the code, replace halibut with the
branch or tag name (such as halibut-1.0). You can see what branches exist using
the command svn ls svn://svn.tartarus.org/sgt. 





-- 
yidabu <yidabu.nospam gmail.com>
D Programming Language China:
http://www.d-programming-language-china.org/
Feb 23 2008
parent DBloke <DBloke nowhere.org> writes:
yidabu wrote:
 I found a good Lightweight markup language, called halitbut (Author Simon
Tatham):
 home: 
 http://www.chiark.greenend.org.uk/~sgtatham/halibut/
 
 It's useful for D programming lanuge DOC, I want to build a halitbut.lib for D
on Windows, but I'm newbie of C language, any one help me to build a
halitbut.lib ?

Why not build a wrapper library for halitbut, D is supposed to interface easily with C, not tried this myself but I believe wxd uses wrapper library's were written in c that d hooks into.
Feb 24 2008