links in manual and graphics

J

Thread Starter

Jiri Baum

Hello,

I just made links between the pages in the manual, so you can go to the
next page instead of having to go to the table of contents all the time.

The links are created from the index.html file by the autolink script, so
there's no need to update them manually.

The actual buttons are rather hastily made, though - I'm just not an
artist. Anyone draw something nicer, please?

Jiri
--
Jiri Baum <[email protected]>
http://www.csse.monash.edu.au/~jiribvisit the MAT LinuxPLC project at http://mat.sf.net

_______________________________________________
LinuxPLC mailing list
[email protected]
http://linuxplc.org/mailman/listinfo/linuxplc
 
G
Hi All,

Has anyone considered using DocBook. It's relatively easy to do a
structured document with DocBook. The DocBook compiler generates nice
linked HTML pages. Besides the "next", "previous", "Table Of Contents"
links on every page, it's relatively trivial task to include cross
references and such.

You can generate HTML, PS, PDF, RTF easily from one source (although I
haven't had much luck so far including graphics in the last three types,
HTML works fine). Here are some documents that I have done in the past:
http://home.twcny.rr.com/embedded/microwin/index.html
Once you get the basic template going writing the documentation is kinda a
cross between coding and using a word processor. I could help you out
getting the basic structure of the document source code started. But I
don't think I can could up with enough time to help write the 'real'
contents of the documents until fall comes around.

Gary James
[email protected]
http://home.twcny.rr.com/embedded/



_______________________________________________
LinuxPLC mailing list
[email protected]
http://linuxplc.org/mailman/listinfo/linuxplc
 
Gary:
> Has anyone considered using DocBook. It's relatively easy to do a
> structured document with DocBook. The DocBook compiler generates nice
> linked HTML pages.

Currently we're using plain HTML pages, mostly because we have experience with those and no experience with DocBook.

> Besides the "next", "previous", "Table Of Contents" links on every page,
> it's relatively trivial task to include cross references and such.

Well, HTML does those...

> You can generate HTML, PS, PDF, RTF easily from one source

The current manual is set up to generate PS and PDF, the latter including the cross-references (so that clicking on a cross-reference in Adobe
Acrobat takes you to the right place - obviously, once it's printed, you have to follow the ``p. 5'' kind of references by flipping paper pages).

Presumably the cross-references are there in the PS, too, but ghostview doesn't show them.

> Once you get the basic template going writing the documentation is kinda
> a cross between coding and using a word processor. I could help you out
> getting the basic structure of the document source code started. But I
> don't think I can could up with enough time to help write the 'real'
> contents of the documents until fall comes around.

Probably best to leave it for now - HTML is a reasonable format that a lot of people know - unless there's a good reason to change.

Jiri
--
Jiri Baum <[email protected]>
http://www.csse.monash.edu.au/~jiribvisit the MAT LinuxPLC project at http://mat.sf.net

_______________________________________________
LinuxPLC mailing list
[email protected]
http://linuxplc.org/mailman/listinfo/linuxplc
 
M

Mario de Sousa

Jiri Baum wrote:
>
> Gary:
> > Has anyone considered using DocBook. It's relatively easy to do a
> > structured document with DocBook. The DocBook compiler generates nice
> > linked HTML pages.
>
> Currently we're using plain HTML pages, mostly because we have experience
> with those and no experience with DocBook.
>
> > Once you get the basic template going writing the documentation is kinda
> > a cross between coding and using a word processor. I could help you out
> > getting the basic structure of the document source code started. But I
> > don't think I can could up with enough time to help write the 'real'
> > contents of the documents until fall comes around.
>
> Probably best to leave it for now - HTML is a reasonable format that a lot
> of people know - unless there's a good reason to change.
>


Well, DocBook does seem like the preferred format latetly, as it is being used by the Linux Documentation project, and what not.

I was just wondering how long this format is going to stay with us, before somebody comes along and decides that some other format is
better. On the other hand, if we can generate html from DocBook, I guess we are covered, as we can always carry on from html if the need arises.

But Jiri, if Gary is willing to help out with the structure, why not give it a go? It might just be easier than what we think. On the other
hand, if things start to become too complicated, we can alwasy just forget about it.

Gary, why don't you give us a short example of what it is like to write for the DocBook format (considering the structure is in place), so we
can get a better grip on what is really in store for us? In other words, become a salesman for a couple of minutes and try and get Jiri to buy the format? ;-)

Cheers,

Mario.

--
----------------------------------------------------------------------------
Mario J. R. de Sousa
[email protected]
----------------------------------------------------------------------------

The box said it requires Windows 95 or better, so I installed Linux

_______________________________________________
LinuxPLC mailing list
[email protected]
http://linuxplc.org/mailman/listinfo/linuxplc
 
G
> Gary, why don't you give us a short example of what it is like to write
> for the DocBook format (considering the structure is in place), so we
> can get a better grip on what is really in store for us? In other words,
> become a salesman for a couple of minutes and try and get Jiri to buy
> the format? ;-)

Okay, I'm not much of a salesman though, that's why I'm in Engineering ;)

If you are familiar with writing HTML the change over to DocBook is relatively painless. You write DocBook in either SGML or XML. Both are similar to HTML, but both are a little more restrictive in their layout. You have to pay a bit more attention to proper structure. In XML they call it a well formed (or not well formed) document.

I've used SGML in the past, but I think that XML is the prefered format for the future. I think that the biggest difference is that XML is case sensitive where SGML is not. I think that you will see most tool suport in XML in the future. At any rate since I'm more familiar with SGML I will use that in these examples.

In DocBook the emphasis is placed on document structure. You define the structure of the document, not the look of the document. I've heard it described as WYSIWYW (What You See Is What You Want) rather than WYSIWYG (What You See Is What You Get). In theory you can tailor the look of the document after the fact by modifying the style sheets when you compile. But I don't know much about that side, I've always used the standard style sheets that come on a RedHat system.

So we are going to layout the document by it's structure. The two most poular starting points are to start with a BOOK or an ARTICLE. A book has chapters, a table of contents, optional index, etc. An article does not have chapters. There are a few other subtle differences but I can't really recall what they are right now.

So here is a book:

&lt;!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
&lt;!ENTITY chapter1 SYSTEM "ch_one.sgml">
&lt;!ENTITY chapter2 SYSTEM "ch_two.sgml">
&lt;!ENTITY chapter3 SYSTEM "ch_three.sgml">
]>

&lt;!--
Copyright 2000, 2001 - Boris Spider, Acme, Inc.
-->

&lt;book id=index>

&lt;bookinfo>

&lt;date>August 6, 2001&lt;/date>
&lt;title>A Romantic Dinner For Two&lt;/title>
&lt;authorgroup>
&lt;author>
&lt;firstname>Boris&lt;/firstname>
&lt;surname>Spider&lt;/surname>
&lt;affiliation>
&lt;jobtitle>Sr. Creepy Crawly&lt;/jobtitle>
&lt;orgname>
&lt;ulink url="http://www.acme.com">Acme, Inc.&lt;/ulink>
&lt;/orgname>
&lt;address>
&lt;email>[email protected]&lt;/email>
&lt;/address>
&lt;/affiliation>
&lt;/author>
&lt;/authorgroup>

&lt;copyright>
&lt;year>2000&lt;/year>
&lt;year>2001&lt;/year>
&lt;holder>Boris the Spider&lt;/holder>
&lt;/copyright>

&lt;/bookinfo>

&lt;chapter id=ch1>&lt;title>Spinning A Web&lt;/title>
&chapter1;
&lt;/chapter>

&lt;chapter id=ch2>&lt;title>Catching A Fly&lt;/title>
&chapter2;
&lt;/chapter>

&lt;chapter id=ch3>&lt;title>Five Best Fly Recipes&lt;/title>
&chapter3;
&lt;/chapter>

&lt;/book>

So there is the base document of a book with three chapters. This will generate a cover page with the author information and copyright info. It will start to form a table of contents. At this point the table of contents will only have the three chapters defined. So right now we probably have two pages with "next", "previous" and "TOC" links created automatically for you.

One nice thing that you can see from this is that each chapter can be easily broken out into different source files. Different authors could work on each chapter and then all the individual pieces can be compiled into one book.

So let's make a chapter:


&lt;!--
Copyright 2001 - Boris Spider, Acme Inc
-->

&lt;section id=ch1.step1><title>Step One: To a Strong Web &lt;/title>
&lt;?dbhtml filename="web_step_one.html">

&lt;para>
This document will guide you through building your very own spider web.
&lt;/para>

&lt;para>
In the following chapters you will also learn how to catch flies and cook
up a fine fly dinner for two.
&lt;/para>

&lt;section><title>Pick a Location&lt;/title>

&lt;para>
The best location for your spider web is out of reach of a dust mop.
But
you want to locate yourself close to a source of flying critters.
&lt;/para>

&lt;/section>

&lt;section><title>Build Your Web&lt;/title>

&lt;para>
You could build a web by typing the following commands on your favorite
Linux box:
&lt;/para>

&lt;screen>
&lt;prompt>$&lt;/prompt> &lt;userinput>tar -xzf my_own_web.tar.gz&lt;/userinput>
&lt;prompt>$&lt;/prompt> &lt;userinput>cd my_own_web&lt;/userinput>
&lt;prompt>$&lt;/prompt> &lt;userinput>./configure&lt;/userinput>
&lt;prompt>$&lt;/prompt> &lt;userinput>./make; make install&lt;/userinput>
&lt;/screen>

&lt;/section>
&lt;/section>

Now we have a couple more pages. Each section forms a new page. And we have the standard "Next", "Previous" and "TOC" links on each page. We also have a few new entries in our table of contents. Right now our table of contents should look something like this:

1. Spinning A Web
Step One: To a Strong Web
Pick a Location
Build Your Web
2. Catching A Fly
3. Five Best Fly Recipes

So writing the document is basically just defining sections and paragraphs and filling in the text. Just like HTML eh? One thing is you don't need to worry about numbering sections. If you add a chapter, a section or a paragraph, DocBook will take care of re-numbering the chapters, re-ordering the "Next" & "Prev" links, and resolving the cross references.

DocBook is geared to documenting software. You can see from the previous chapter that it has tags specifically for showing user interaction at the command line. There are also tags for function declarations, variable names, constant names, directory paths and file names, code snippets, etc....


The second chapter has a link back to the first chapter. If for some reason the Author of the first chapter missed the cross reference DocBook will give you a warning message when you compile but otherwise ignore the missing link. You will not end up with 404 errors in the generated HTML code. I did a function reference for the Microwindows project and made all of the cross references follow a pretty simple naming standard. When I wanted to make a cross reference, it was pretty easy to make the link without manually looking it up in the target document. If you set up some cross reference naming convention between two authors, then within reason you can link away to the other chapter. When all is done the DocBook compiler will let you know through warnings where unresolved references are. If you want to fix them okay, if not then ignore the warnings.

Here is the second chapter:

&lt;!--
Copyright 2001 - Boris Spider, Acme Inc
-->

&lt;section id=ch2.step1>&lt;title>Setting The Bait&lt;/title>
&lt;?dbhtml filename="catch_step_one.html">

&lt;para>
This chapter is pretty short. It just has
&lt;link linkend=ch1.step1>this link&lt;/link> back to the first chapter.
&lt;/para>

&lt;/section>


And before I forget, we have one more page now with the obligatory "Next", "Prev", "TOC" buttons. Here is the table of contents now.

1. Spinning A Web
Step One: To a Strong Web
Pick a Location
Build Your Web
2. Catching A Fly
Setting The Bait
3. Five Best Fly Recipes


In DocBook you can do tables and lists. The last chapter of our book has a simple list.

&lt;!--
Copyright 2001 - Boris Spider, Acme Inc
-->

&lt;section id=ch3.step1>&lt;title>Recipes&lt;/title>
&lt;?dbhtml filename="recipes.html">

&lt;para>
This chapter contains my favorite Fly recipes for a romantic evening. Be
warned that having a romantic dinner with the Widow in black, will
generally
result in you being the main entree.
&lt;/para>

&lt;orderedlist numeration="lowerroman">
&lt;listitem>
&lt;para>French Flies&lt;/para>
&lt;/listitem>
&lt;listitem>
&lt;para>Fly ala Mode&lt;/para>
&lt;/listitem>
&lt;listitem>
&lt;para>Fly Bean Salad&lt;/para>
&lt;/listitem>
&lt;listitem>
&lt;para>XX-tra Hot Buffalo Flies&lt;/para>
&lt;/listitem>
&lt;listitem>
&lt;para>Fly Pad Prig Pow&lt;/para>
&lt;/listitem>
&lt;/orderedlist>
&lt;/section>

Copy these four chunks of SGML code to the files "fly.sgml", "ch_one.sgml", "ch_two.sgml", and "ch_three.sgml". If your on a RedHat system (I'm not sure what for another system) type this command "db2html fly.sgml" and you will end up with the HTML documentation that can be found here: http://home.twcny.rr.com/embedded/fly


Here are some nice DocBook links:

DocBook The Definitive Guide (a must read once you get going, it also covers all of the special tags that I didn't even begin to mention):
http://www.docbook.org/tdg/en/html/docbook.html
Linux Documentation Project Author Guide:
http://www.linuxdoc.org/LDP/LDP-Author-Guide/index.html
DocBook dot Org
http://www.docbook.org/
A Practical Introduction to DocBook:
http://www.oswg.org/oswg-nightly/oswg/en_US.ISO_8859-1/articles/DocBook-Intro/docbook-intro.html

Gary James
[email protected]
http://home.twcny.rr.com/embedded/
_______________________________________________
LinuxPLC mailing list
[email protected]
http://linuxplc.org/mailman/listinfo/linuxplc
 
Top