622 lines
18 KiB
HTML
622 lines
18 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
|
|
<HTML>
|
|
<HEAD>
|
|
<TITLE>An Explanation of the Sample Plug-In SGML source template</TITLE>
|
|
</HEAD>
|
|
|
|
<BODY text="#111111" bgcolor="#ffffff"
|
|
vlink="#59559C" alink="#33CC33" link="#AC3035" >
|
|
|
|
<H4>"Linux Gazette...<I>making Linux just a little more fun!</I>
|
|
"</H4>
|
|
|
|
<P> <HR> <P>
|
|
|
|
<!--======================================================================-->
|
|
|
|
From mjhammel@csn.net <BR>
|
|
Subject: Re: Gimp Tips & Tricks <BR>
|
|
Date: Thu, 5 Sep 1996 22:39:21 -0600 (MDT) <BR>
|
|
<P>
|
|
I have written a template for use by GIMP plug-in authors to write documentation
|
|
that will look good and be fairly uniform for our users. There is also a
|
|
detailed explanation that goes with it. The explanation is, in a sense, a
|
|
general explanation on how to use the LinuxDoc package, since that's what
|
|
we've decided to use for the GIMP Documentation Project.
|
|
<P>
|
|
You can take a look at both the template and the explanation at:
|
|
<A HREF="http://www.csn.net/~mjhammel/gimp/gdp/gdp.html">
|
|
http://www.csn.net/~mjhammel/gimp/gdp/gdp.html</A> (look under the plug-ins
|
|
documentation section). The explanation text follows below.
|
|
<P>
|
|
--
|
|
Michael J. Hammel | Lottery: A tax on people who are bad at math.<BR>
|
|
<A HREF="mailto:mjhammel@csn.net">mjhammel@csn.net</A>,
|
|
<A HREF="http://www.csn.net/~mjhammel">http://www.csn.net/~mjhammel</A>
|
|
|
|
<!--===================================================================-->
|
|
|
|
<P> <HR> <P>
|
|
<CENTER>
|
|
<H1>An Explanation of the Sample Plug-In SGML source template</H1>
|
|
<FONT size="2">
|
|
Copyright 1996
|
|
<BR>by
|
|
</FONT>
|
|
<FONT size="3">
|
|
Michael J. Hammel <A HREF="mailto:mjhammel@csn.net">mjhammel@csn.net</A>
|
|
</FONT>
|
|
<FONT size="2">
|
|
<BR>Last Updated: 09/04/96
|
|
</FONT>
|
|
</CENTER>
|
|
<P>
|
|
|
|
This is a long page, but don't let that scare you. Creating your documents
|
|
in SGML and using LinuxDoc tools to create your HTML, GNU Info, Man Page,
|
|
or other formats is really pretty simple. This page just happens to be
|
|
fairly thorough in explaining how to get it all done.
|
|
|
|
<P>
|
|
There are 6 sections in the SGML template:
|
|
|
|
<UL>
|
|
<LI><A HREF="#title">The Title Information Section</A>
|
|
<LI><A HREF="#intro">The Introduction Section</A>
|
|
<LI><A HREF="#features">The Features Section</A>
|
|
<LI><A HREF="#dialog">The Dialog Box Section</A>
|
|
<LI><A HREF="#examples">The Examples Section</A>
|
|
<LI><A HREF="#notes">The Notes Section</A>
|
|
</UL>
|
|
|
|
Each section is described below. Along with these, there are a number of
|
|
things you should be aware of when writing your document:
|
|
<UL>
|
|
<LI><A HREF="#toc">The Table of Contents</A>
|
|
<LI><A HREF="#sections">Section markers</A>
|
|
<LI><A HREF="#paragraphs">Forcing new paragraphs</A>
|
|
<LI><A HREF="#comments">Comments</A>
|
|
<LI><A HREF="#lists">Lists</A>
|
|
<LI><A HREF="#examples">HTML or other format Specific tags</A>
|
|
<LI><A HREF="#various-formats">Notes about creating documents in the various formats</A>
|
|
</UL>
|
|
|
|
As far as LinuxDoc itself is concerned, here are some things you might want
|
|
to be aware of:
|
|
<UL>
|
|
<LI>Where to get the LinuxDoc software:
|
|
<UL>
|
|
<LI><A HREF="http://www.informatik.tu-muenchen.de/~schwarz/linuxdoc-sgml/">
|
|
The Home Page for LinuxDoc.</A>
|
|
<LI>FTP Sites:
|
|
<UL>
|
|
<LI><A HREF="ftp://ftp.cc.gatech.edu/pub/people/gregh/linuxdoc-sgml/linuxdoc-sgml-1.5.tar.gz">
|
|
ftp://ftp.cc.gatech.edu/pub/people/gregh/linuxdoc-sgml/linuxdoc-sgml-1.5.tar.gz</A>
|
|
<LI><A HREF="ftp://tsx-11.mit.edu/pub/linux/docs/linuxdoc-sgml-1.5.tar.gz">
|
|
ftp://tsx-11.mit.edu/pub/linux/docs/linuxdoc-sgml-1.5.tar.gz</A>
|
|
<LI><A HREF="ftp://sunsite.unc.edu/pub/Linux/utils/text/linuxdoc-sgml-1.5.tar.gz">
|
|
ftp://sunsite.unc.edu/pub/Linux/utils/text/linuxdoc-sgml-1.5.tar.gz</A>
|
|
<LI>
|
|
<A HREF="ftp://ftp.cc.gatech.edu/pub/people/gregh/linuxdoc-sgml">
|
|
ftp://ftp.cc.gatech.edu/pub/people/gregh/linuxdoc-sgml</A>
|
|
- Uptodate patches to version 1.5.
|
|
</UL>
|
|
</UL>
|
|
<LI><A HREF="#test-sgml">How to test your SGML</A>
|
|
<LI><A HREF="#linuxdoc-updates">Updates I've made to the LinuxDoc package</A>
|
|
</UL>
|
|
|
|
If you're interested in testing your SGML source, you should grab a copy of
|
|
the LinuxDoc package at (put ftp site here).
|
|
|
|
<HR>
|
|
|
|
<A NAME="title"></A>
|
|
<H2>The Title Information Section</H2>
|
|
This section has 6 tags in it:
|
|
<UL>
|
|
<LI>article
|
|
<LI>title
|
|
<LI>author
|
|
<LI>inst
|
|
<LI>date
|
|
<LI>abstract
|
|
</UL>
|
|
|
|
All of these tags are mandatory and <B>must</B> be placed in this order.
|
|
|
|
<P>
|
|
The <I>article</I> tag has no other text associated with it. It is put on
|
|
a line by itself and is a marker to the SGML parser telling the parser what
|
|
kind of document is to be created.
|
|
<BR>
|
|
Example:
|
|
<PRE>
|
|
<article>
|
|
</PRE>
|
|
|
|
<P>
|
|
The <I>title</I> tag is the name of the Plug-In. This must be one line
|
|
long and on the same line as the <I>title</I> tag.
|
|
<BR>
|
|
Example:
|
|
<PRE>
|
|
<title>The Sparkle Plug-In
|
|
</PRE>
|
|
|
|
<P>
|
|
The <I>author</I> tag identifies the author of the Plug-In. This should
|
|
simply be the name of the developer. Along with this is a tag which
|
|
identifies the email address of the author.
|
|
The code for the email address looks similar to the following.
|
|
<BR>
|
|
Example:
|
|
<BR>
|
|
<PRE>
|
|
<author>Michael J. Hammel
|
|
<htmlurl url="mailto:user@some.net" name="&lt;user@some.net&gt;">
|
|
</PRE>
|
|
<P>
|
|
Just substitute the appropriate email address. Note that the use of
|
|
<CODE> &amplt; </CODE>
|
|
and
|
|
<CODE> &ampgt; </CODE>
|
|
are required. These get translated into the less-than
|
|
and greater-than signs, respectively, in the output.
|
|
|
|
<P>
|
|
The <I>inst</I> tag is just the current version number of the Plug-In
|
|
source code.
|
|
<BR>
|
|
Example:
|
|
<PRE>
|
|
<inst>Version 1.0
|
|
</PRE>
|
|
|
|
<P>
|
|
The <I>date</I> tag is the date that the source code was last updated. The
|
|
format of the text that goes with this tag should look like the following:
|
|
<BR>
|
|
Example:
|
|
<PRE>
|
|
<date>Last Updated: 09/01/96
|
|
</PRE>
|
|
|
|
<P>
|
|
The <I>abstract</I> tag marks the beginning of a paragraph of text that
|
|
describes, in general, what the Plug-In does. This is free formatted text
|
|
and must be followed by the <abstract> tag.
|
|
<BR>
|
|
Example:
|
|
<PRE>
|
|
<abstract>
|
|
Some text goes here.
|
|
</abstract>
|
|
</PRE>
|
|
|
|
<HR>
|
|
|
|
|
|
<A NAME="intro"></A>
|
|
<H2>The Introduction Section</H2>
|
|
|
|
This section contains two subsections:
|
|
<UL>
|
|
<LI>Where to get the software
|
|
<LI>How to build the software
|
|
</UL>
|
|
|
|
Both of these are mandatory subsections.
|
|
<P>
|
|
Example section header:
|
|
<PRE>
|
|
<sect>Introduction
|
|
<P>
|
|
</PRE>
|
|
|
|
<P>
|
|
The <I>Where to get the software</I> subsetion is a URL (ftp or http address)
|
|
for the source code.
|
|
If a binary version is available, the binaries location should be listed with
|
|
the this subsection.
|
|
<BR>
|
|
Example:
|
|
<PRE>
|
|
<sect1>Where to get the software
|
|
<P>
|
|
The software can be retrieved from
|
|
<htmlurl url="ftp://ftp.some.net/dir/file.tar.gz"
|
|
name="&lt;ftp://ftp.some.net/dir/file.tar.gz&gt;">
|
|
</PRE>
|
|
|
|
<P>
|
|
The <I>How to build the software</I> subsetion is simple an explanation
|
|
on how to build the software.
|
|
Example:
|
|
<PRE>
|
|
<sect1>How to build the software
|
|
<P>
|
|
Building the source should be fairly straight forward.
|
|
Just make sure the LIBS= line points to the location of
|
|
libgimp.a. Also, a copy of gimp.h is included in the
|
|
source. You should really delete this and make gimp.h a
|
|
symbollic link to your copy of gimp.h (wherever you're
|
|
keeping that) so that the latest version of gimp.h is used.
|
|
</PRE>
|
|
|
|
|
|
<HR>
|
|
|
|
<A NAME="features"></A>
|
|
<H2>The Features Section</H2>
|
|
|
|
The <I>Features Section</I> is an itemized list of the features that the plug-in
|
|
provides. This should include, at a minimum, a listing of all the buttons,
|
|
sliders, or input fields in the dialog box. A very brief description of
|
|
the features can be included. This is desirable if the feature listed is
|
|
not one that is readily apparent from the dialog box.
|
|
|
|
<P>
|
|
Example:
|
|
<PRE>
|
|
<sect>Features
|
|
<P>
|
|
<itemize>
|
|
<item>Feature one
|
|
<item>Feature two
|
|
<item>Feature three
|
|
</itemize>
|
|
</PRE>
|
|
|
|
See the section titled <I><A HREF="#lists">Lists</A></I> for a description
|
|
on how to create lists using the template.
|
|
|
|
|
|
<HR>
|
|
|
|
<A NAME="dialog"></A>
|
|
<H2>The Dialog Box Section</H2>
|
|
|
|
The <I>Dialog Box Section</I> describes the features found in the Plug-In's
|
|
pop-up dialog box and explains how they effect images. This section is
|
|
made up of an screen capture image (for the HTML formatted output files)
|
|
of the dialog box, an numbered list of features, and a feature-by-feature
|
|
breakdown.
|
|
|
|
To start this section, use the followgin:
|
|
<PRE>
|
|
<sect>The ... Dialog Box <label id="dialog">
|
|
<P>
|
|
</PRE>
|
|
Replace the three dots with the name of the Plug-In.
|
|
|
|
<P>
|
|
After the section header, a list of features should be provided. The list
|
|
will look something like this following:
|
|
<PRE>
|
|
<itemize>
|
|
<item><em><ref id="feature1" name="Feature One"></em>
|
|
<item><em><ref id="feature2" name="Feature Two"></em>
|
|
<item><em><ref id="feature3" name="Feature Three"></em>
|
|
</itemize>
|
|
</PRE>
|
|
|
|
The <I>name</I> tag is what will show up in the list. The <I>id</I> tag is
|
|
a cross reference that you will use later. The <I><em></I> tags just cause
|
|
the stuff inbetween to be put in italics.
|
|
|
|
<P>
|
|
After you create the list, you should force a break after the image. This
|
|
will only affect HTML output for now.
|
|
|
|
This is the line you should add to force the break:
|
|
<PRE>
|
|
<![%fmthtml; [ <? <BR clear="both"> > ]]>
|
|
</PRE>
|
|
|
|
<P>
|
|
Now you should add the subsections that fully explain each feature. For
|
|
the first item in the list above, you would add the following:
|
|
|
|
<PRE>
|
|
<sect1>Feature One <label id="feature1">
|
|
<P>
|
|
This is the text explaining the first feature.
|
|
</PRE>
|
|
|
|
The <I>sect1</I> tag signifies you are starting a subsection. The
|
|
<I>label</I> with its <I>id</I> gives this section a name that can be used
|
|
as a cross-reference. We used this in the list of features earlier.
|
|
|
|
<P>
|
|
You would have a subsection just like this for each feature in your dialog
|
|
box.
|
|
|
|
<HR>
|
|
|
|
<A NAME="examples"></a>
|
|
<H2>The Examples Section (and how to use format-specific tags)</H2>
|
|
|
|
<P>
|
|
This section is more complex than the others. Examples of how the GIMP
|
|
Plug-Ins work aren't of much use without some images to go with them.
|
|
Unfortunately, not all output formats support images (remember: we're using
|
|
SGML so we can create HTML, info, man pages, and whatever other formats
|
|
are supported by the LinuxDoc package). We need to force this section to
|
|
be processed differently depending on which formatter we're running the
|
|
SGML source through. The way we do this is to use format-specific tags and
|
|
the SGML equivalent of an escape sequence. You're already seen one of
|
|
these in the section where we forced an HTML break tag. The generic format
|
|
of this SGML tag is:
|
|
|
|
<PRE>
|
|
<![%fmttag; [ <? ... > ]]>
|
|
</PRE>
|
|
|
|
Where <I>fmttag</I> is one of
|
|
<UL>
|
|
<LI>fmthtml
|
|
<LI>fmttxt
|
|
<LI>fmttex
|
|
<LI>fmtrtf
|
|
<LI>and so forth
|
|
</UL>
|
|
|
|
and the 3 dots are the format-specific text you want to be passed directly
|
|
to the output file. If the sgml parser sees the <I>fmttag</I> tag and it
|
|
matches the output format you've requested then the format-specific text is
|
|
written to the output file. If it doesn't match the format requested, the
|
|
text is ignored.
|
|
|
|
<P>
|
|
Thats the technical explanation. Whats worse is it doesn't appear to work
|
|
(or I'm doing it wrong - one of the two).
|
|
|
|
<P>
|
|
Until I figure this problem out you have one of two choices:
|
|
<UL>
|
|
<LI>Put in a URL pointing to examples on some other page
|
|
<LI>Use the Sparkle SGML source as an example.
|
|
</UL>
|
|
|
|
The former of these can be done with the following line:
|
|
<PRE>
|
|
<htmlurl url="http://www.some.net/dir/file.html"
|
|
name="&lt;http://http.some.net/dir/file.html&gt;">
|
|
</PRE>
|
|
|
|
Just substitute the appropriate URL.
|
|
|
|
<P>
|
|
The latter of the two options can be downloaded from
|
|
<A HREF="http://www.csn.net/~mjhammel/gimp/gdp/plug-ins/sparkle.sgml">
|
|
http://www.csn.net/~mjhammel/gimp/gdp/plug-ins/sparkle.sgml</A>. You may
|
|
need to hold down the <I>Shift</I> key to force this file to be downloaded
|
|
and not displayed.
|
|
|
|
<HR>
|
|
|
|
<A NAME="notes"></a>
|
|
<H2>The Notes Section</H2>
|
|
The <I>Notes Section</I> is the place to stuff everything that doesn't fit
|
|
neatly into the other sections, such as known bugs, limitations, or future
|
|
enhancements that are planned.
|
|
|
|
<P>
|
|
Example:
|
|
<PRE>
|
|
<sect>Notes
|
|
<P>
|
|
</PRE>
|
|
|
|
|
|
<HR>
|
|
|
|
<A NAME="toc"></A>
|
|
<H2>The Table of Contents</H2>
|
|
|
|
This is a single line that goes immediately after the <I>Title Information
|
|
Section</I> and immediately before the <I>Introduction Section</I>.
|
|
It should look exactly like this:
|
|
|
|
<P>
|
|
<PRE>
|
|
<toc>
|
|
</PRE>
|
|
|
|
|
|
<HR>
|
|
|
|
<A NAME="sections"></A>
|
|
<H2>Section Markers</H2>
|
|
|
|
There are several layers of sections available, but we only require the top
|
|
two:
|
|
<PRE>
|
|
<sect>
|
|
<sect1>
|
|
</PRE>
|
|
|
|
The <I>sect</I> tag forces a new page in the output files. The <I>sect1</I>
|
|
just gets another type of formatting on that same page. You can add
|
|
<I>sect2</I> and <I>sect3</I> levels if you want, but I'm not sure what
|
|
they do to the output.
|
|
|
|
<P>
|
|
Note that you <B>must</B> put the following immediately after the section
|
|
tags:
|
|
<PRE>
|
|
<p>
|
|
</PRE>
|
|
|
|
This tells the SGML parser to end the section header and begin the part of
|
|
the document that belongs in that section.
|
|
|
|
|
|
<HR>
|
|
|
|
<A NAME="paragraphs"></A>
|
|
<H2>Forcing new paragraphs</H2>
|
|
This is simple, just add the following:
|
|
<PRE>
|
|
<p>
|
|
</PRE>
|
|
|
|
Note that its also possible to use blank lines to force new paragraphs, but
|
|
whether the SGML parser uses the blank line as a paragraph or not depends
|
|
on where its used. Its easier to just use the above tag to be sure.
|
|
|
|
|
|
<HR>
|
|
|
|
<A NAME="comments"></A>
|
|
<H2>Comments</H2>
|
|
|
|
If you want to put comments in your SGML, you would do it like so:
|
|
<PRE>
|
|
<-- This is an SGML Comment line -->
|
|
</PRE>
|
|
Note that this is very similar to the HTML comment.
|
|
|
|
|
|
<HR>
|
|
|
|
<A NAME="lists"></A>
|
|
<H2>Lists</H2>
|
|
|
|
To create a bulleted list, do the following:
|
|
<PRE>
|
|
<itemize>
|
|
<item>Item one
|
|
<item>Item two
|
|
<item>Item three
|
|
</itemize>
|
|
</PRE>
|
|
|
|
To create a numbered list, do the following:
|
|
<PRE>
|
|
<enum>
|
|
<item>Item one
|
|
<item>Item two
|
|
<item>Item three
|
|
</enum>
|
|
</PRE>
|
|
Pretty straight forward, really.
|
|
|
|
|
|
<HR>
|
|
|
|
<A NAME="test-sgml"></A>
|
|
<H2>How to test your SGML</H2>
|
|
You can verify your SGML documentation will work with the various format
|
|
converters by running it through each one. For example, to check if you
|
|
can get the HTML output with an SGML file called <I>plugin.sgml</I>, try:
|
|
<PRE>
|
|
sgml2html plugin
|
|
</PRE>
|
|
|
|
To get text output, try:
|
|
<PRE>
|
|
sgml2txt plugin
|
|
</PRE>
|
|
|
|
To get man page output in groff format, try:
|
|
<PRE>
|
|
sgml2txt -man plugin
|
|
</PRE>
|
|
|
|
You should read the man pages for each of the sgml2<whatever>
|
|
commands to learn the command line options. They are really pretty easy to
|
|
use.
|
|
|
|
|
|
<HR>
|
|
|
|
<A NAME="linuxdoc-updates"></A>
|
|
<H2>Updates I've made to the LinuxDoc package</H2>
|
|
I've made two distinct changes to the LinuxDoc package. The first is to
|
|
the linuxdoc.dtd file, found under the <TT>lib/dtd</TT> directory after you
|
|
unpack LinuxDoc. The following was added right before the last line:
|
|
|
|
<PRE>
|
|
<!-- added fmt* which were somehow missing -->
|
|
<!-- default is ignore, override on commandline in sgml2* -->
|
|
<!entity % fmttex "ignore">
|
|
<!entity % fmthtml "ignore">
|
|
<!entity % fmttxt "ignore">
|
|
<!entity % fmtinfo "ignore">
|
|
<!entity % fmtrtf "ignore">
|
|
<!entity % fmtlyx "ignore">
|
|
</PRE>
|
|
|
|
These allow for format-specific tags in the SGML source so you can, for
|
|
example, add a graphic in your HTML output but just include the description
|
|
of the image in your text output.
|
|
|
|
<P>
|
|
The other change was to the html2html.l flex file under html-fix. The
|
|
changes aren't complex, but theres a number of them to allow for command
|
|
line options to set the background, text, and link colors. If you want
|
|
this I can send it to you, but its not really necessary to test your SGML
|
|
before submitting it to me.
|
|
|
|
|
|
<HR>
|
|
|
|
<A NAME="various-formats"></A>
|
|
<H2>Notes about creating documents in the various formats</H2>
|
|
First of all, there are a set of scripts in LinuxDoc for creating documents
|
|
in the various formats:
|
|
<UL>
|
|
<LI>sgml2html
|
|
<LI>sgml2txt
|
|
<LI>sgml2info
|
|
<LI>sgml2rtf
|
|
<LI>sgml2lyx
|
|
<LI>sgml2latex
|
|
</UL>
|
|
|
|
<B>Note</B>:
|
|
In order to do format specific tagging, you'll need to update your
|
|
linuxdoc.dtd file. See the section on
|
|
LinuxDoc Updates (found on the website listed in the introductory section
|
|
of this article) for the details.
|
|
|
|
<P>
|
|
The first of these, sgml2html, was used to create the new Sparkle
|
|
documentation, as well as the HTML version of the SGML template. It works
|
|
quite well using "free-formatted" input files. By free-formatted I mean
|
|
that the actual text (not the formatting tags) can be one word per line or
|
|
any number of words per line and the output will come out nicely formatted
|
|
using as many words as will fit in your web browser.
|
|
|
|
<P>
|
|
The text formatter, sgml2txt, also works quite well. The output has
|
|
various formatting characters that work well with the "less" and, possibly,
|
|
"more" pagers.
|
|
|
|
<P>
|
|
The GNU Info formatter, sgml2info, is not happy with such free formatting
|
|
of the text, however.
|
|
|
|
|
|
<P>
|
|
I have not tried the other formatters yet. I don't know what RTF is and
|
|
I've not used the Lyx or Latex tools so I'm not sure how to test the output
|
|
from these formatters.
|
|
<P>
|
|
Michael J. Hammel
|
|
|
|
<!--===================================================================-->
|
|
<P> <hr> <P>
|
|
<A HREF="./index.html"><IMG ALIGN=BOTTOM SRC="../gx/indexnew.gif"
|
|
ALT="[ TABLE OF CONTENTS ]"></A>
|
|
<A HREF="../index.html"><IMG ALIGN=BOTTOM SRC="../gx/homenew.gif"
|
|
ALT="[ FRONT PAGE ]"></A>
|
|
<A HREF="netday.html"><IMG SRC="../gx/back2.gif"
|
|
ALT=" Back "></A>
|
|
<A HREF="dynamicweb.html"><IMG SRC="../gx/fwd.gif" ALT=" Next "></A>
|
|
<P> <hr> <P>
|
|
</BODY>
|
|
</HTML>
|