"Linux Gazette...making Linux just a little more fun! "

From mjhammel@csn.net
Subject: Re: Gimp Tips & Tricks
Date: Thu, 5 Sep 1996 22:39:21 -0600 (MDT)

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.

You can take a look at both the template and the explanation at: http://www.csn.net/~mjhammel/gimp/gdp/gdp.html (look under the plug-ins documentation section). The explanation text follows below.

-- Michael J. Hammel | Lottery: A tax on people who are bad at math.
mjhammel@csn.net, http://www.csn.net/~mjhammel

An Explanation of the Sample Plug-In SGML source template

Copyright 1996
by Michael J. Hammel mjhammel@csn.net
Last Updated: 09/04/96

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.

There are 6 sections in the SGML template:

Each section is described below. Along with these, there are a number of things you should be aware of when writing your document: As far as LinuxDoc itself is concerned, here are some things you might want to be aware of: If you're interested in testing your SGML source, you should grab a copy of the LinuxDoc package at (put ftp site here).

The Title Information Section

This section has 6 tags in it: All of these tags are mandatory and must be placed in this order.

The article 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.
Example: 

	<article>

The title tag is the name of the Plug-In. This must be one line long and on the same line as the title tag.
Example: 

	<title>The Sparkle Plug-In

The author 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.
Example: 

	<author>Michael J. Hammel
	<htmlurl url="mailto:user@some.net" name="&lt;user@some.net&gt;">

Just substitute the appropriate email address. Note that the use of &amplt; and &ampgt; are required. These get translated into the less-than and greater-than signs, respectively, in the output.

The inst tag is just the current version number of the Plug-In source code.
Example: 

	<inst>Version 1.0

The date 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:
Example: 

	<date>Last Updated: 09/01/96

The abstract 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.
Example: 

	<abstract>
		Some text goes here.
	</abstract>

The Introduction Section

This section contains two subsections: Both of these are mandatory subsections.

Example section header: 

	<sect>Introduction
	<P>

The Where to get the software 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.
Example: 

	<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;">

The How to build the software subsetion is simple an explanation on how to build the software. Example: 

	<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.

The Features Section

The Features Section 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.

Example: 

	<sect>Features
	<P>
	<itemize>
		<item>Feature one
		<item>Feature two
		<item>Feature three
	</itemize>
See the section titled Lists for a description on how to create lists using the template.

The Dialog Box Section

The Dialog Box Section 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: 
	<sect>The ... Dialog Box <label id="dialog">
	<P>
Replace the three dots with the name of the Plug-In.

After the section header, a list of features should be provided. The list will look something like this following: 

	<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>
The name tag is what will show up in the list. The id tag is a cross reference that you will use later. The <em> tags just cause the stuff inbetween to be put in italics.

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: 

	<![%fmthtml; [ <? <BR clear="both"> > ]]>

Now you should add the subsections that fully explain each feature. For the first item in the list above, you would add the following: 

	<sect1>Feature One <label id="feature1">
	<P>
	This is the text explaining the first feature.
The sect1 tag signifies you are starting a subsection. The label with its id gives this section a name that can be used as a cross-reference. We used this in the list of features earlier.

You would have a subsection just like this for each feature in your dialog box.

The Examples Section (and how to use format-specific tags)

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: 

	<![%fmttag; [ <? ... > ]]>
Where fmttag is one of 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 fmttag 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.

Thats the technical explanation. Whats worse is it doesn't appear to work (or I'm doing it wrong - one of the two).

Until I figure this problem out you have one of two choices:

The former of these can be done with the following line: 
	<htmlurl url="http://www.some.net/dir/file.html" 
	name="&lt;http://http.some.net/dir/file.html&gt;">
Just substitute the appropriate URL.

The latter of the two options can be downloaded from http://www.csn.net/~mjhammel/gimp/gdp/plug-ins/sparkle.sgml. You may need to hold down the Shift key to force this file to be downloaded and not displayed.

The Notes Section

The Notes Section 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.

Example: 

	<sect>Notes
	<P>

The Table of Contents

This is a single line that goes immediately after the Title Information Section and immediately before the Introduction Section. It should look exactly like this: 

	<toc>

Section Markers

There are several layers of sections available, but we only require the top two: 
	<sect>
	<sect1>
The sect tag forces a new page in the output files. The sect1 just gets another type of formatting on that same page. You can add sect2 and sect3 levels if you want, but I'm not sure what they do to the output.

Note that you must put the following immediately after the section tags: 

	<p>
This tells the SGML parser to end the section header and begin the part of the document that belongs in that section.

Forcing new paragraphs

This is simple, just add the following: 
	<p>
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.

Comments

If you want to put comments in your SGML, you would do it like so: 
	<-- This is an SGML Comment line -->
Note that this is very similar to the HTML comment.

Lists

To create a bulleted list, do the following: 
	<itemize>
		<item>Item one
		<item>Item two
		<item>Item three
	</itemize>
To create a numbered list, do the following: 
	<enum>
		<item>Item one
		<item>Item two
		<item>Item three
	</enum>
Pretty straight forward, really.

How to test your SGML

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 plugin.sgml, try: 
	sgml2html plugin
To get text output, try: 
	sgml2txt plugin
To get man page output in groff format, try: 
	sgml2txt -man plugin
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.

Updates I've made to the LinuxDoc package

I've made two distinct changes to the LinuxDoc package. The first is to the linuxdoc.dtd file, found under the lib/dtd directory after you unpack LinuxDoc. The following was added right before the last line: 
<!-- 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">
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.

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.

Notes about creating documents in the various formats

First of all, there are a set of scripts in LinuxDoc for creating documents in the various formats: Note: 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.

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.

The text formatter, sgml2txt, also works quite well. The output has various formatting characters that work well with the "less" and, possibly, "more" pagers.

The GNU Info formatter, sgml2info, is not happy with such free formatting of the text, however.

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.

Michael J. Hammel

[ TABLE OF CONTENTS ] [ FRONT PAGE ] Back Next