File: plugin.gimp.html

package info (click to toggle)
lg-issue10 2-4
links: PTS
area: main
in suites: hamm, slink
size: 560 kB
ctags: 100
sloc: makefile: 30; sh: 3
file content (621 lines) | stat: -rw-r--r-- 18,007 bytes
parent folder | download | duplicates (3)
<!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>&quot;Linux Gazette...<I>making Linux just a little more fun!</I>
&quot;</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>
	&lt;article&gt;
</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>
	&lt;title&gt;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>
	&lt;author&gt;Michael J. Hammel
	&lt;htmlurl url="mailto:user@some.net" name="&amp;lt;user@some.net&amp;gt;"&gt;
</PRE>
<P>
Just substitute the appropriate email address.  Note that the use of
<CODE> &amp;amplt; </CODE>
and 
<CODE> &amp;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>
	&lt;inst&gt;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>
	&lt;date&gt;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 &lt;abstract&gt; tag.
<BR>
Example:
<PRE>
	&lt;abstract&gt;
		Some text goes here.
	&lt;/abstract&gt;
</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>
	&lt;sect&gt;Introduction
	&lt;P&gt;
</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>
	&lt;sect1&gt;Where to get the software
	&lt;P&gt;
	The software can be retrieved from
	&lt;htmlurl url="ftp://ftp.some.net/dir/file.tar.gz" 
	name="&amp;lt;ftp://ftp.some.net/dir/file.tar.gz&amp;gt;"&gt;
</PRE>

<P>
The <I>How to build the software</I> subsetion is simple an explanation
on how to build the software.
Example:
<PRE>
	&lt;sect1&gt;How to build the software
	&lt;P&gt;
	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>
	&lt;sect&gt;Features
	&lt;P&gt;
	&lt;itemize&gt;
		&lt;item&gt;Feature one
		&lt;item&gt;Feature two
		&lt;item&gt;Feature three
	&lt;/itemize&gt;
</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>
	&lt;sect&gt;The ... Dialog Box &lt;label id="dialog"&gt;
	&lt;P&gt;
</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>
	&lt;itemize&gt;
		&lt;item&gt;&lt;em&gt;&lt;ref id="feature1" name="Feature One"&gt;&lt;/em&gt;
		&lt;item&gt;&lt;em&gt;&lt;ref id="feature2" name="Feature Two"&gt;&lt;/em&gt;
		&lt;item&gt;&lt;em&gt;&lt;ref id="feature3" name="Feature Three"&gt;&lt;/em&gt;
	&lt;/itemize&gt;
</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>&lt;em&gt;</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>
	&lt;![%fmthtml; [ &lt;? &lt;BR clear="both"&gt; &gt; ]]&gt;
</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>
	&lt;sect1&gt;Feature One &lt;label id="feature1"&gt;
	&lt;P&gt;
	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>
	&lt;![%fmttag; [ &lt;? ... &gt; ]]&gt;
</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>
	&lt;htmlurl url="http://www.some.net/dir/file.html" 
	name="&amp;lt;http://http.some.net/dir/file.html&amp;gt;"&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>
	&lt;sect&gt;Notes
	&lt;P&gt;
</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>
	&lt;toc&gt;
</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>
	&lt;sect&gt;
	&lt;sect1&gt;
</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>
	&lt;p&gt;
</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>
	&lt;p&gt;
</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>
	&lt;-- This is an SGML Comment line --&gt;
</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>
	&lt;itemize&gt;
		&lt;item&gt;Item one
		&lt;item&gt;Item two
		&lt;item&gt;Item three
	&lt;/itemize&gt;
</PRE>

To create a numbered list, do the following:
<PRE>
	&lt;enum&gt;
		&lt;item&gt;Item one
		&lt;item&gt;Item two
		&lt;item&gt;Item three
	&lt;/enum&gt;
</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&lt;whatever&gt;
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>
&lt;!-- added fmt* which were somehow missing --&gt;
&lt;!-- default is ignore, override on commandline in sgml2* --&gt;
&lt;!entity % fmttex  "ignore"&gt;
&lt;!entity % fmthtml "ignore"&gt;
&lt;!entity % fmttxt  "ignore"&gt;
&lt;!entity % fmtinfo "ignore"&gt;
&lt;!entity % fmtrtf  "ignore"&gt;
&lt;!entity % fmtlyx  "ignore"&gt;
</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="./lg_toc10.html"><IMG ALIGN=BOTTOM SRC="../gx/indexnew.gif" 
ALT="[ TABLE OF CONTENTS ]"></A>
<A HREF="../lg_frontpage.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>