Hello Jacinta,
> [...] we write our course notes with a text editor in sgml
> and then use sgmltools, jadetex, pdfeTeX, ps2pdf etc to get a pdf we
can print
> and distribute. We also have some of our more recent course notes
written in
> pod and use pod2docbook (our customised copy) to add that into the chain.
>
> [...] I love having plain text files to edit and being able
> to use all the regular tools such as diff and CVS to manage changes.
[...]
>
> [...] I don't understand how docbook works, and I have no idea
> how to convert our system from using the scheme-like DTD DSSSL Style
Sheet to
> using something I do understand.
>
> I'm seriously considering alternate ways to build our course notes,
and I'd love
> to know what you do, and how that works for you.
I am writing my notes as plain text files in PerlPoint
(perlpoint.sf.net) and then process them into paged HTML for the slides
to present (each headline starts a new slide), and into PDF for the
printed handouts using sdf and ghtmldoc (generating PDF from HTML from
SDF from PerlPoint).
As I am one of the authors of PerlPoint I will try to avoid too much
advertising (please see http://perlpoint.sf.net for for a feature list,
overview and tutorial). It's just the tool I am using myself in course
preparation for years now. It is not perfect (and still improved), but
handy to produce both slides and PDF from one source (or a set of nested
sources, respectively). Complex tasks can be hidden in macros written in
Perl, macros can be used team-wide.
Some basic formatting rules like the paragraph principle and the basic
tag syntax are similar to POD so if one knows POD it should feel
familiar. Existing POD files can be processed directly by using import
filters.
It's all written in Perl. Output generation can be adapted by
overwriting methods in derived classes (although this API needs more
documentation).
The PDF look is based on the features provided by ghtmldoc, which
includes a well looking generated TOC with chapter links, linked local
TOCs, links to chapters and self-defined anchors, external URLs, tables,
images, (kind of) footnotes, and formatting both in descriptions and
examples. ghtmldoc allows to configure various aspects of the page
layout - there might be more, but the required basics are well supported.
As a disadvantage, bullet list points are more indented than examples in
ghtmldoc PDFs (perhaps it is possible to arrange that better?). I would
also like to have colored text in the PDF, but that's not supported at
the moment (but b/w text is suitable for printed handouts). The subset
of (intermediately used) HTML that is understood by ghtmldoc is limited,
and it ignores CSS, so one gets a rather basic layout, but of a good
quality.
For HTML output, perlpoint.sf.net and the public version of the German
Perl Workshop CD (http://puck.perl-workshop.de/ocd2007pub/index.html)
are examples of larger documents that are available online (please use
another browser than IE to look at them, we recently found an IE related
layout requirement that is not applied to the public pages yet).
Basically, the layout is determined by user provided HTML templates
(called "styles") with placeholders for the generated parts. These
styles can use CSS, Javascript etc. and are selected by an option, so
one can switch between them.
Best regards
Jochen
