Date: Fri, 3 Sep 1999 15:17:35 +0100 From: Nik Clayton <nik@freebsd.org> To: Eric Brunner <brunner@world.std.com> Cc: doc@FreeBSD.ORG Subject: Re: Query -- editor(s) Message-ID: <19990903151735.G99849@kilt.nothing-going-on.org> In-Reply-To: <199909022351.TAA26000@world.std.com>; from Eric Brunner on Thu, Sep 02, 1999 at 07:51:22PM -0400 References: <199909022351.TAA26000@world.std.com>
next in thread | previous in thread | raw e-mail | index | archive | help
On Thu, Sep 02, 1999 at 07:51:22PM -0400, Eric Brunner wrote:
> What are my choices for writing, assuming that for some reason(s)
> I want some degree of consistency between what I am writing and
> the handbook? For the moment, assume that I'm writing a section,
> knowing my material, but using vi and no tool (or method) more
> sophisticated than occasionally browsing a page-in-progress. I'm
> more than a little concerned that producing subsequent work for
> publication (in roff, TeX, or Postscript) from my common text will
> require more work later...
I *think* this is two questions -- the first is which DTD, the second
is which editor makes using that DTD simple.
The DTD choice is easy -- DocBook, or the FreeBSD extended version of
it (which only adds a few new elements, which you may not need.
The editor choice is more personal. I use Xemacs, because the SGML
editing support is pretty good, and it's got nice pull down menus so
I don't go mad trying to learn all the M-x combinations (selecting
"Regexp replace" from a menu is better for me than trying to remember
whether it's "M-x replace-regexp" or "M-x regexp-replace", or whatever
the actual function is called).
Other's mileage may vary.
That lets you write the 'source' to your document. For easy viewing,
you probably then want to be able to 'compile' it to HTML, or Postscript.
For that you can use the tools in the textproc/docproj port (Jade and
TeX, specifically). This will give you the same 'look and feel' as the
FDP documents that are currently available.
Those are quite 'big' tools though, and can take some time to process
large documents. You may find it easier to use a tool like sgmlfmt
(also in the docproj port) which is smaller and faster -- your HTML
output won't look the same, which is probably not a problem, and you
can still preview your work.
> So, if I were the happy volunteer who drew the short straw for
> the jrandom section of the handbook, posessed only of 2.2.8, what
> would be my production tool kit?
My personal approach would be to try and install the docproj port, and
see how much of that works on 2.2.8. Jade *should*, but it's been a
long time since I tried it.
If it does work, then great, because you can lever the FDP make
infrastructure to make using the tools a no-brainer. You can download
the doc/share/* and doc/en_US.ISO_8859-1/* directories from CVS, and then
add your document under the hierarchy, copy and tweak one of the existing
Makefiles, and away you go.
If Jade doesn't work then you can fall back to using sgmlfmt and related
apps. These aren't used by the FDP anymore, but you can see examples of
their use in the /usr/share/mk/bsd.sgml.mk file.
Use whichever editor you're comfortable with. If it's got hooks for
processing SGML documents then so much the better.
N
--
[intentional self-reference] can be easily accommodated using a blessed,
non-self-referential dummy head-node whose own object destructor severs
the links.
-- Tom Christiansen in <375143b5@cs.colorado.edu>
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?19990903151735.G99849>