Skip site navigation (1)Skip section navigation (2)
Date:      Wed, 14 May 1997 19:03:02 +0100
From:      Nik Clayton <nik@blueberry.co.uk>
To:        questions@freebsd.org
Cc:        doc@freebsd.org
Subject:   Re: Is Thot (WYSIWIG editor) for you?
Message-ID:  <19970514190302.20618@blueberry.co.uk>
In-Reply-To: <3379F24B.934@fps.biblos.unal.edu.co>; from Pedro F. Giffuni on Wed, May 14, 1997 at 10:11:39AM -0700
References:  <14271.863600208@time.cdrom.com> <3379F24B.934@fps.biblos.unal.edu.co>

next in thread | previous in thread | raw e-mail | index | archive | help
On Wed, May 14, 1997 at 10:11:39AM -0700, Pedro F. Giffuni wrote:
> Jordan K. Hubbard wrote:
> > 
> > > What I am pitching is for is that if Thot is good we can start advertising it
> > > and hopefully standardize our internal documentation based on its format.
> > > Internal documentation meaning things like : reports, articles, etc...
> > 
> > But we already have such a standard and it's called SGML....
> 
> SGML is a format, Thot is a toolset and an editor. Correct me if I'm
> wrong, but I haven't seen a good SGML tool in our ports tree.

Sort of right, sort of wrong.

> Thot produces Latex and HTML. AFAIK HTML is a subset of SGML, so I
> guess Thot fits into the "standard".

My $0.02 follows. I haven't used Thot (no Motif license) but I have
trawled the FTP site, and read the docs. Doubtless John Fieber will 
jump in if I have any of this wrong.

SGML is a meta-language. It describes other languages. HTML is one language
that can be described by SGML. There are many others.

One of these others is called DocBook. Current thinking on the FreeBSD
documentation project (of which I am not a member) is to move from
using the LinuxDoc TeX format to writing documents marked up according
to the DocBook style. Once this is done, HTML can be produced, as can
plain text, PostScript and so on.

DocBook is also *much* more expressive than HTML is. For example, a
snippet of some docs I'm converting to DocBook (and will then be
submitting to the project as a tutorial) is

    <para><filename>/var/tmp/root</filename> now contains all the files that
    should be placed in appropriate locations below <filename>/</filename>. 
    You now have to go through each of these files, determining how they 
    differ from your existing files. This is not a task that can be 
    automated (at the moment).</para>

    <para>Note that some of the files that will have been installed in
    <filename>/var/tmp/root</filename> have a leading '.'. Make sure you use
    <command/ls -a/ to catch them.</para>

As you can see, there is extra markup in there to denote things like
commands, and filenames. There are many, many more.

This sort of verbosity in the markup is a Good Thing. It allows more
useful searches of the information to be carried out. It makes it
easier to ensure that information is presented consistently. And it
retains as much semantic information about the documentation as
possible.

Eventually, *all* FreeBSD project documentation will be written with
DocBook, in much the same way as it's currently written in LinuxDoc.

What is needed, as far as I can tell, is a decent environment for
editing these files. Ideally, it should :-

  1 Understand an SGML DTD, and prevent you creating invalid documents 
    according to the specification

  2 Have an editor that makes editing DocBook as painless as possible.
    Drop down lists of styles. A sample 'WYSIWYG' display[1], that sort
    of thing

  3 Make it easy to convert DocBook documents to other formats

[1] I *know* this term cannot really be applied to semantic markup.
However, an editor that supported variable-width fonts, allowed the tags
to be hidden, showed different marked up sections in different
colours/styles, and was user configurable, would be very handy.

We don't have a one stop shop that does all that. Yet.

The SGML tools take care of point 1. But they don't do it interactively.
It's like writing code, you have the "Edit; Compile; Fix; Compile"
cycle.

We don't have anything close to 2. The nearest product, as far as I can
tell, would be SoftQuad's Author/Editor, which doesn't run on Intel
unices anyway (it does, however, work with Win3.1/95, how are the WINE
folks getting on :-) ). More info on it at

    http://www.softquad.co.uk/products/authored/

If my understanding of Thot is correct, *Thot does not do this*. It uses
it's own styles and is not SGML aware.

Point 3 is handled. At least, I know of (and use) a DocBook -> HTML
converter. DocBook -> Text can be kludged with Lynx. 

Right now, I do all this with Xemacs, the SGML tools that come with 2.2,
back fitted to 2.1.7, and a Makefile to automate the conversions. It's
not pretty, but it works. John Fieber's documentation at 

    http://fallout.campusview.indiana.edu/~jfieber/docbook/

was invaluable in getting me kickstarted.

IMHO, what's needed is for people with an interest in the documentation
to build a nice editing environment (based around whichever editor
people feel most comfortable with), all the necessary tools, and some
samples of documentation -- a cookbook, if you will -- that makes it
simpler for people who have the urge to get involved. Plus, of course,
documentation so that people can use this.

Make it available as a package/port, and make sure it works across as
many versions of FreeBSD as possible. 

I can do some of this. I could probably port the tools (tho' I've never
attempted a port before). I could write some of the first-time user
documentation. I could write sample documents to show the range of
DocBook markup available. But, I can't do all of it. And I'm probably
not qualified to anyway, since I have my own questions for the Doc
project gurus to answer.

Thoughts?

I've cc'd this to the 'doc' mailing list, which is (I guess) where this
sort of discussion should really be taking place, instead of on
questions-.

N
-- 
--+=[ Blueberry Hill                  Blueberry New Media                ]=+--
--+=[ http://www.blueberry.co.uk/     1/9 Chelsea Harbour Design Centre, ]=+--
--+=[ WebMaster@blueberry.co.uk       London, England, SW10 0XE          ]=+--
--+=[       Those who do not read Dilbert are doomed to repeat it        ]ENTP



Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?19970514190302.20618>