Proposal to use Docbook to make tutorials...

Started by RickJ, Sun 27/04/2003 23:49:01

Previous topic - Next topic

RickJ

I have been working with Docbook for the past few weeks and it's pretty cool.  

For those of you who are unfamiliar with it, docbook  is a widely accepted XML standard and is similar to HTML.  The difference is that docbook tags are used to define what the enclosed content is rather than how it looks.   The result is a document source file that is easily converted to single or multiple html files, pdf file, html help (chm) files,and other formats.  Table of Contents, index, and glossaries are automatically generated and the document look and feel is determined by reuseable stylesheets.  Professional publishers use this system extensively.   Actually, I believe that a form of docbook (SGML) standard was the forerunner of HTML and XML.  

The problem we have with AGS tutorials at the moment is that they are all in different formats and are widely scattered amoung our individual websites.  We seledom share these with each other because of the amount of work involved in reformatting them to have a consistent look.

I think that using docbook to make AGS tutorials would solve this and other problems by providing the following benefits:

  • Documents by various authors would be consistent with each other.  
  • Collections of documents from different authors could be easily created and provided to the community.  
  • The "look" of a document, or collections of documents, can easily be changed by modifying style sheets and republishing from the source.
  • Documents can be provided in different formats without any additional work.
  • Since the author doesn't need to worry about the final format, only the content, it is easier to make the document is this respect.
  • Automatic table of contents and index generation.  In the case of HTML these are hyper linked.
  • Fairly easy to learn to use.  
Here is an example tutorial I have created using this standard.  The HTML headers and footers are from a slightly modified  default stylesheet.  These can be changed as we see fit.  

Here is an example of the single HTML output format...
Example HTML

Here is a zip of the complete example including the source document mingt.xml, and the CHM, Multiple HTML, Single HTML, and PDF outputs formats.
Complete Example (300k zip)

Here is an alpha version of the compelete system.  This system was an open source project sponsored by [urlwww.e-novative.de/docbook[/url].   The original system uses a command line interface.  I have used AGS to create an intuitive GUI front end, in cooperation with e-novative.  The command line version is at V1.01 (or soimething like that).  The GUI is at the Alpha-2 stage.  You can download the complet thing from here if you want to try it.    

Complete Publishing System (28Mb zip)

To install this just unzip it to c:\docbook.  You will need to install a java jre if you don't have one already.  There is one included in the zip, just goto the docbook/jre folder and run jre.exe.

To run the GUI just go to the c:\docbook directory and click on the short-cut eDE or goto the gui directory and run ede.exe

The example document is mingt.

Well, I am curious as to your opinions of all this.  At least take this time to look at the source and output files.  Keep in mind that you edit the the document.xml source file and then run a program to generate the HTML, PDF, CHM files.  

Thanks to Scorpiorus and Jimi for their indespensible help on this project.

I know this last statement should be obvious but you would be suprised to know that an entire General Electric Engineering department spent nearly 10 years whining and complaining about how the  productivity tools  I made for them were a pain in the ass.  I could never understand their position, until I returned 10 years later as a consultant and they showed me how they were editing the text processor output files and were therfore manually editing page numbers and table of contents, instead of  letting the damm computer do the work.  

So I appologize for talking down to everyone, I assume you got it, but just in case I thought I would be clear. :)  To this day I still can't believe this whole bunch of engineers are so dense!!!






remixor

Though I don't really make many tutorials, I think this is a great idea, and I would second this motion.  XML is a great format, and is really infinitely versatile.  RickJ did a good job of explaining it, but I hope he doesn't mind that I put a small example just to demonstrate how it works without having to open hisexample file, and why it's so useful.  This is just a random example I made up, since in XML you in essence can "create your own" tags.

It works in a similar way to HTML.  So in your source document, let's say you want the title and author's name displayed in different ways from the regular body text.  Instead of putting in font and size tags in the source itself, you could just do this:
<title>Tutorial</title>
<author>by Remixor</author>
Now, this isn't like standard HTML where those tags always mean fixed things.  In your stylesheet document, you would defite <title> and <author> to mean whatever you want.  So if you wanted the title to be in bold and font size +2, you would indicate that in the stylesheet.  Somebody else could take the exact same source file, and could apply to it a different stylesheet, one that instead took titles and made them italicised.  See what I mean?  The same document can be used to generate multiple pages, all with the same content but different formatting.  So as RickJ said, this still allows different authors to make their tutorials fit with the rest of their webpage or whatever, but still in a standardized format such that if someone was to make a compilation, he could simply apply the same stylesheet to all the documents and they would all be formatted the same.

I hope that was clear.  I most likely repeated some stuff from RickJ's post, so I apologize for possibly being redundant.   As you can see it's quite a simple format to use.  BTW, people could also share stylesheets.  That way if you don't really want to bother with the formatting side of things, you can just type up your content with XML tags and use someone else's stylesheet.

I hope I haven't made any mistakes in my explanation here.  RickJ, if you notice anything I should change, let me know.  Basically I'm just very much in support of this proposal so I want people to understand what a useful technology this is.
Writer, Idle Thumbs!! - "We're probably all about video games!"
News Editor, Adventure Gamers

RickJ

remixor:  Thanks for your comments and additional explanation.  Just to clarify, about stylesheets for everyone, I would expect that we could have a default set of stylesheets available that everyone could use.  The only time someone would need to make their own stylesheets is if they wanted to have their own tutorial format for whatever reason.  So don't get the idea that everytime you make a tutorial you need to make stylesheets.  

The other thing cool thing is that it is as easy as pushing a button to get everything in CHM form, just like the AGS help file.  If we get enough useful contributions then perhaps some future version of AGS would have a means of opening these from within the editor?  So to add a tutorial you would just download the chm file and put it in the AGS (or some other) folder and bamo it would show up in a menu somewhere in AGS.  

Note the reason the full system is such a big download is that it includes a Java JRE (it's required for the XML and FOP processors) and some other executables (i.e. programs) used to edit and manipulate XML.  I think, in the future  the system will be broken up into multiple downloads, so that the size will be less of a problem.

Here is a snipet of the XML that produced the HTML file ilink in the first post.
Quote<article lang="en">
  <articleinfo>
     <title>Creating a Minimal Game Template</title>
     <pubdate>March 23, 2003</pubdate>
     <copyright>
        <year>2003</year>
        <holder>BluSoft</holder>
     </copyright>
     <legalnotice>
        <para>
       Copyright © 2002 e-novative GmbH. All rights reserved. No part of this publication may be reproduced,
       transmitted, transcribed, stored in a retrieval system, or translated into any language in any form by
       any means without prior written permission of e-novative GmbH.  This publication is provided as is, without
       warranty of any kind, either express or implied, including, without limitation, the implied warranties of
       merchantability, fitness for particular purpose, or noninfringement. The entire risk arising out of the use
       of this publication remains with the recipient.  To the maximum extent permitted by applicable law, in no event
       shall e-novative be liable for any special, incidental, indirect, or consequential damages whatsoever (including,
       without limitation, damages for loss of business or loss of business profits, business interruption or loss of
       business information) arising out of the use of software and/or information as described in this publication, even
       if e-novative has been advised of the possibility of such damages. Any brand and product names mentioned in this
       document might be trademarks or registered trademarks of their respective owners in Germany and/or other countries.
    </para>
     </legalnotice>
     <author><firstname>Dan</firstname><surname>Jones</surname></author>
     <author><firstname>Rick</firstname><surname>Jafrate</surname></author>
  </articleinfo>

  <abstract>
     <para>
        This tutorial explains how to create a minimal game template by removing
    non-essential elements from a default AGS game project.  This is typically
    done in preparation for the importation of script modules, GUI interfaces,
    characters, and etc.
     </para>
  </abstract>
 
  <sect1><title>Introduction</title>
     <sect2><title>Overview</title>
        <para>
           A new game, when created by AgsEdit, contains a default collection of sprites,
       OS, and global script code that allows a game designer to begin creating rooms
       with a minimal amount of effort.  This is fine for novices and experimenters but
       in many instances more experienced designers prefer to start from their own code
       base. In this case it is convenient to have a game template that has as little
       content as possible and still compile without errors.
        </para>
     </sect2>





Joseph DiPerla

I like this idea. It seems very organised and could be helpful.

Joey
Joseph DiPerla--- http://www.adventurestockpile.com
Play my Star Wars MMORPG: http://sw-bfs.com
See my Fiverr page for translation and other services: https://www.fiverr.com/josephdiperla
Google Plus Adventure Community: https://plus.google.com/communities/116504865864458899575

Jimi

DocBook seems like an extremely helpful thing to use and know how to use.

Rick puts forward a very good point about how tutorials are scattered. DocBook seems the perfect thing to make tutorials in.

I think it would be a great idea ifmost of them were put into one file.

Pumaman

This does look cool, I have to say - actually, it looks better than the crappy tex2rtf thing I'm using to generate the AGS help file, so I might have to switch.

RickJ

CJ:  Wow, thanks for the compliment.  Just understand it's still an Aplha version.  Speaking of compliments, here's what Stefan over at e-novative had to say about AGS.

Quote
Rick,

Things look pretty nice! It's amazing what you have achieved in that short
period of time. Now I surely understand why you chose AGS. Well, here's
what I've come up with after some initial testing:

> -  Your opinion of  the GUI alpha version, bugs, modifications, and
> additions.

- I can't get most things to work, in most batch files an error message
appears that the label "translation" cannot be found (Win2000). Not dure
if this this is a GUI or a Win98 vs. Win NT issue
- the "dummy" document should not appear in the document lists. It exists
because we had a problem with creating empty direcories, but is no
document that can be processed
- the GUI should remember the selected document on each pane. When I
switch panes, the first document in the list is selected; it would be an
advantage to keep the selected document since in most cases one will
perform a sequence of processing steps on a "current" document
- in the popup windows, I cannot move the cursor, but only use the
backspace key. It would be nice to be able to move the cursor to prevent
deleting the whole line just to edit a typo right at the beginning

This is how far I got, I was trying to find the source of the batch
error(s), but did not succeed that quickly.

> - Output directories and commands, I think this doesn't work in all cases
In which cases did you have problems with it?

> - Document types and stylesheets, Can a type include which style sheets
> to be used as well as the xml template?
I'm not sure if I understand what you mean. The type (article or book)
defines the template that is used. The XSL stylesheets are divided per
type and per output format to allow full customization of the output. The
user should not change any e_novative* stylesheet but create a custom*
stylesheet. The e-novative stylesheets provide the default values that can
be changed by upgrading eDE, still the custom settings will be kept. You
can also create a document-specific stylesheet by creating a
document_(name).xsl file.

> - Distribution files size, Can it be split into smaller modules? JRE
> seperate download and install, etc?.
I was considering that before. The problem is the "dumb" users that just
download, click-and-install and expect everything to work. I am planning
on distributing incremental upgrades, however, so the users only have to
download and install the big packag once

> - Seperate user documents from docbook system directory,  Use document
> configuration file?
> - Location of docbook installation directory?
You can put the user documents into another place by setting the
repository variable in the configuration batch. That's the reason why the
document templates have a hardcoded "file"-reference that points to the
original Docbook DTD in c:\docbook\dtd. And this is exactly the main
problem with installing eDE to some other path

So, what do you think we need to do to get the three versions of batch
files (original, W98 and GUI) in sync? The goal should be to have one set
of batch files, everything else calls for serious trouble on the road, I
think.

Kind regards,

Stefan Priebsch
CEO

---
>e-novative> - e-Business Software & Solutions
Isartorplatz 3 - 80331 Munich - Germany

http://www.e-novative.de

I'll keep everyone posted as this project progresses.

Cheers

Jimi


Scorpiorus

#8
Woohoo... ;D You released the docbook Rick! Can't wait to test it! :P
I hadn't i-net for about two weeks because of my provider (.........!). Now I have one but the connection speed......is slow so I am afraid I can't download it right now.  :-\ When I'll do I post the full feedback to the thread.

PS Great work! ;)

Cheers,
Scorp

Jimi

Your not the only one scorp!....s....l....o....w.... :'(

SMF spam blocked by CleanTalk