Return to runoff-like markup language

[n***@tessellation.com]

I write courses to teach OOAD, C++, and Java.
In the past, I've used ClarisWorks (now AppleWorks) to write the
course, converting to PDF to give to printers.
It's becoming too difficult to use a WYSIWYG method to write courses.
I'd rather (gasp! horrors!) return to what I did in the 1970's, with
tools like runoff, and write the course in marked-up text something
like:

.page
.title How to make a function overrideable
Add the keyword virtual to the function's declaration.
.code
virtual void foo();
.end
.image virtual_function.jpg

etc.

This would allow me to establish one font for ".code", with automatic
return to the "normal" font when the ".code" was matched with ".end".

Automatic generation of a table of contents would be heavenly.

Converting the text to PDF would be delightful.

Does anyone have any clues for me to find something like this?

Many thanks,

Robert Allan Schwartz
Senior Instructor
Tessellation Training

[Peter Flynn]

Post by n***@tessellation.com
I write courses to teach OOAD, C++, and Java.
In the past, I've used ClarisWorks (now AppleWorks) to write the
course, converting to PDF to give to printers.
It's becoming too difficult to use a WYSIWYG method to write courses.
I'd rather (gasp! horrors!) return to what I did in the 1970's, with
tools like runoff, and write the course in marked-up text something
.page
.title How to make a function overrideable
Add the keyword virtual to the function's declaration.
.code
virtual void foo();
.end
.image virtual_function.jpg
etc.
This would allow me to establish one font for ".code", with automatic
return to the "normal" font when the ".code" was matched with ".end".
Automatic generation of a table of contents would be heavenly.
Converting the text to PDF would be delightful.
Does anyone have any clues for me to find something like this?

XML would do this kind of thing very easily. The markup is a little
denser than RUNOFF style, but using the right editor it needn't be
intrusive.

<tip>
<title>How to make a function overrideable</title>
<programlisting>virtual void foo();</programlisting>
<graphic file="virtual_function" type="jpg"/>
</tip>

The advantage is XML's robustness, the fact that it has heavy support,
and that vocabularies exist for many applications, epecially computer
documentation. Because it is platform- and environment-independent, it
can easily be transformed into HTML, PDF, etc. The fact that it has
become the de facto standard for this kind of work implies to me that
using RUNOFF-like markup is really not an option these days.

///Peter

[Jeroen van Holst]

Post by n***@tessellation.com
It's becoming too difficult to use a WYSIWYG method to write courses.
I'd rather (gasp! horrors!) return to what I did in the 1970's, with
tools like runoff, and write the course in marked-up text something
Does anyone have any clues for me to find something like this?

Perhaps you're looking for groff, it comes standard with most Linux
distributions and I see there's even a version for Windows.

[Vityok]

What you have written is very like the nroff which comes with almost
all modern UNIX clones (like FreeBSD, LiNUX based and so on).

But, I think, you should also consider using DocBook. It has pretty
verbose vocabulary already, and a pretty good set of tools that support
it. It can be authored in SGML or XML. DocBook allows you to use the
source of your document for producing PDF, RTF, HTML pages quite
nativelly.

One more choice is to use LaTeX. It also has lots of good features,
but, is not an XML application but rather a set of extensions for TeX.

There are utilities which convert DocBook to LaTeX. Thus, you will get
a possibility to utilize extraordinary powerful TeX typesetting
capabilities.

[bugbear]

Post by n***@tessellation.com
I write courses to teach OOAD, C++, and Java.
In the past, I've used ClarisWorks (now AppleWorks) to write the
course, converting to PDF to give to printers.
It's becoming too difficult to use a WYSIWYG method to write courses.
I'd rather (gasp! horrors!) return to what I did in the 1970's, with
tools like runoff, and write the course in marked-up text something
.page
.title How to make a function overrideable
Add the keyword virtual to the function's declaration.
.code
virtual void foo();
.end
.image virtual_function.jpg

A wysiwig tool with good style sheets can do this
for you, bringing you the best of both worlds.

BugBear

[Aandi Inston]

Post by n***@tessellation.com
.page
.title How to make a function overrideable
Add the keyword virtual to the function's declaration.
.code
virtual void foo();
.end
.image virtual_function.jpg
etc.
This would allow me to establish one font for ".code", with automatic
return to the "normal" font when the ".code" was matched with ".end".

Any serious document preparation tool, such as FrameMaker, and even
Word, will allow you to create character styles. I would go so far as
to say you should never, ever, explicitly change font or paragraph
settings in a serious document: always create suitable styles and work
with them.

Post by n***@tessellation.com
Automatic generation of a table of contents would be heavenly.

Ditto the same tools.

Post by n***@tessellation.com
Converting the text to PDF would be delightful.

Ditto (with Acrobat for Word).

Of course, there are many runoff-like languages around, and the main
one in serious use are those based on TeX, such as LaTeX. These are
especially favoured where WYSIWIG tools are weak, such as in
mathematical formulae, and where automatic generation (e.g. of
directories or dictionaries) is wanted. But be sure you haven't just
missed out on the right way to use the tools you have.
----------------------------------------
Aandi Inston ***@dial.pipex.com http://www.quite.com
Please support usenet! Post replies and follow-ups, don't e-mail them.

[Vityok]

To say the truth, MS Word and alike are not well suited for preparation
of structured content of a size bigger than 5 pages [that is from my
sad experience of working with that toy].

I think, that DocBook XML can give you the best from the XML and LaTeX
worlds as, again, there are DocBook -> LaTeX conversion utilities [see
http://sf.net], and you will be able to write content in What You See
Is What You Mean fashion.

[Aandi Inston]

Post by Vityok
To say the truth, MS Word and alike are not well suited for preparation
of structured content of a size bigger than 5 pages [that is from my
sad experience of working with that toy].

Word does tend to collapse on larger documents, though it works pretty
well on shorter ones. I wrote a manual with it once, never again.
FrameMaker I would recommend for long document work that is not too
layout sensitive.
----------------------------------------
Aandi Inston ***@dial.pipex.com http://www.quite.com
Please support usenet! Post replies and follow-ups, don't e-mail them.

[Shmuel (Seymour J.) Metz]

In <***@f14g2000cwb.googlegroups.com>, on
01/16/2006

Subject: Return to runoff-like markup language

Return to? I never left. Since you posted to comp.text.sgml, you must
be aware that such languages have been available all along.

It's becoming too difficult to use a WYSIWYG method to write
courses.

The software that is touted as WYSIWYG invariably turns out to be what
you see is all you get (WYSIAYG).

I'd rather (gasp! horrors!) return to what I did in the 1970's, with
tools like runoff, and write the course in marked-up text

AKA a return to sanity.

Does anyone have any clues for me to find something like this?

Google for DocBook and for LaTEX. Those are far from the only options.