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.
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:
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.
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.
<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.
<author>Michael J. Hammel <htmlurl url="mailto:email@example.com" name="<firstname.lastname@example.org>">
Just substitute the appropriate email address. Note that the use of
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
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:
<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.
<abstract> Some text goes here. </abstract>
Example section header:
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.
<sect1>Where to get the software <P> The software can be retrieved from <htmlurl url="ftp://ftp.some.net/dir/file.tar.gz" name="<ftp://ftp.some.net/dir/file.tar.gz>">
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.
<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.
<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.
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
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:
<htmlurl url="http://www.some.net/dir/file.html" name="<http://http.some.net/dir/file.html>">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.
<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.
<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.
<-- This is an SGML Comment line -->Note that this is very similar to the HTML comment.
<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.
sgml2html pluginTo get text output, try:
sgml2txt pluginTo get man page output in groff format, try:
sgml2txt -man pluginYou 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.
<!-- 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.
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