Has anyone used DocBook? (for documentation)

Promote Puppy !
Post Reply
Message
Author
User avatar
puppian
Posts: 537
Joined: Tue 19 Jul 2005, 03:58
Location: PuppyLand
Contact:

Has anyone used DocBook? (for documentation)

#1 Post by puppian »

http://packages.debian.org/stable/text/docbook
"DocBook is an SGML document type definition (DTD) that is well-suited to books, articles, or reference documentation about technical matters, systems, or software (although it is by no means limited to these applications)...."

It's used by the Linux Documentation Project.
Has anyone tried it? Would it be useful for Puppy documentation?

See also:
http://www.docbook.org/
http://www.oasis-open.org/docbook/sgml/
http://docbook.sourceforge.net/
Last edited by puppian on Mon 17 Oct 2005, 14:26, edited 3 times in total.
[url=http://puppylinux.org]Puppylinux.org - Community home page of Puppy Linux[/url] hosted by Barry (creator of Puppy), created and maintained by the [url=http://puppylinux.org/user/readarticle.php?article_id=8]Puppy Linux Foundation[/url] since 2005

User avatar
puppian
Posts: 537
Joined: Tue 19 Jul 2005, 03:58
Location: PuppyLand
Contact:

#2 Post by puppian »

Linux Documentation Project homepage:
http://tldp.org/

There are lots of documents and are well-organized. DocBook seems able to output files in different formats (pdf, html...) too.
[url=http://puppylinux.org]Puppylinux.org - Community home page of Puppy Linux[/url] hosted by Barry (creator of Puppy), created and maintained by the [url=http://puppylinux.org/user/readarticle.php?article_id=8]Puppy Linux Foundation[/url] since 2005

User avatar
Ian
Official Dog Handler
Posts: 1234
Joined: Wed 04 May 2005, 12:00
Location: Queensland

#3 Post by Ian »

As Puppy uses Dillo I would suggest that the documentation be written in HTML.

Mozilla has Composer which simplifies HTML writing, you can create the documentation by just writing in the Normal section and edit in the Source section if necessary.

This is how I do my documentation, it is quicker and easier than writing everything in HTML. I only edit the source for special things.

You might be able to convert the HTML to PDF or text then PDF I have never looked into this.

User avatar
puppian
Posts: 537
Joined: Tue 19 Jul 2005, 03:58
Location: PuppyLand
Contact:

#4 Post by puppian »

Ian wrote:As Puppy uses Dillo I would suggest that the documentation be written in HTML.
Actually I don't know what's "SGML document type definition" and what docBook does (so I started the topic :)) From your answer it seems that docBook doesn't output html directly ... if so then it's not so useful. I thought docBook maybe useful just because the linux documentation project looks cool (their pages are well-organized and all pages look the same/similar in style, though they are written by different people). Maybe some CMS (Content Management System) php scripts can do that too?
Ian wrote:Mozilla has Composer which simplifies HTML writing, you can create the documentation by just writing in the Normal section and edit in the Source section if necessary.

This is how I do my documentation, it is quicker and easier than writing everything in HTML. I only edit the source for special things.
Oh yes I do that too, though sometimes with NVU in Windoz :oops: The only cons of Composer and NVU is that the output file is not so stardard (i.e. may not display the same on different browsers). The best html editor I've ever used is DreamWeaver, but it's huge and non-free :(
Ian wrote:You might be able to convert the HTML to PDF or text then PDF I have never looked into this.
That's easy with Windows, with puppy seems not yet... (thoughtjourney's puppyPDF will convert text to pdf thou). I found this which converts .doc to pdf but it seems that much works needed for it to work in puppy. Perhaps there's an abiword plugin that does the same thing?
[url=http://puppylinux.org]Puppylinux.org - Community home page of Puppy Linux[/url] hosted by Barry (creator of Puppy), created and maintained by the [url=http://puppylinux.org/user/readarticle.php?article_id=8]Puppy Linux Foundation[/url] since 2005

User avatar
Lobster
Official Crustacean
Posts: 15522
Joined: Wed 04 May 2005, 06:06
Location: Paradox Realm
Contact:

#5 Post by Lobster »

I have done a lot of trials for tmxxine on documentation and my conclusion is this:

Content is more important than format

One of the great things about Puppy is the wizards - which also EXPLAIN what is being done and why.

The simpler and more obvious and functional something is the less documentation

However - HTML is already being used as is Wiki (usually HTML or just text) so we already are doing the Documentation in the right format . . . HTML or plain text will go into most formats . . .

Agree with you about Dreamweaver - one prog I miss . . .
Puppy Raspup 8.2Final 8)
Puppy Links Page http://www.smokey01.com/bruceb/puppy.html :D

raffy
Posts: 4798
Joined: Wed 25 May 2005, 12:20
Location: Manila

Quick HTML page

#6 Post by raffy »

As I promised to do this during the Foundation Week, here is the link to the HTML help page tutorial (images are not so nice - they're done outside Puppy - am on trip so have no access to PuppyPC).

http://www.ph-islands.net/example/
Last edited by raffy on Mon 17 Oct 2005, 13:02, edited 1 time in total.

User avatar
Lobster
Official Crustacean
Posts: 15522
Joined: Wed 04 May 2005, 06:06
Location: Paradox Realm
Contact:

#7 Post by Lobster »

Thanks raffy

I found your page a little confusing

Here is a simple page I created on making HTML
http://pages.britishlibrary.net/tooting/webdesign.html

(I created the website where it is housed incidentally)

It refers to notepad - just use leafpad or Beaver (which has HTML colour coding) or Puppys Bluefish
Puppy Raspup 8.2Final 8)
Puppy Links Page http://www.smokey01.com/bruceb/puppy.html :D

User avatar
puppian
Posts: 537
Joined: Tue 19 Jul 2005, 03:58
Location: PuppyLand
Contact:

#8 Post by puppian »

Lobster wrote:I have done a lot of trials for tmxxine on documentation and my conclusion is this:

Content is more important than format
Totally agree. I don't care about the format at all! I mentioned pdf just because someone else in the forum said they want it (they may have some points thou, as html print differently on different computers with different browsers; with pdf it looks the same whereever you print it)
Lobster wrote:One of the great things about Puppy is the wizards - which also EXPLAIN what is being done and why.
Sure! Puppy wizards are great! They teach me a lot 8)
Lobster wrote:The simpler and more obvious and functional something is the less documentation
I don't think Puppy should have too much docs either. I like simple things too (so I seldom write very long documentation ;))

So don't take me wrong, I'm NOT focusing on the format. What I mean really is:
puppian wrote:...pages are well-organized and all pages look the same/similar in style, though they are written by different people...
IMO an ideal documentaion software should be something like this:

1. simple and easy to use
2. have things like templates; e.g. the user only have to imput the content in an input box (much like posting in this forum), but there would be more than one input box. so the content of each box becomes a section of the output page (similar to 'section-editing in Media wiki?); this way only few formatting rules are needed (only BBCode perhaps); and editing is done mostly in plain text
3. user can select which catergory a page go to after creating it with just one click
4. table of content / sitemap and index are generated automatically (again with just one click :))
5. output files are easy to navigate (with menu/sidebar/anchor, etc)
6. easy submition/integration of new docs by different writters (e.g. people just click a "submit" button to submit a new page and the table of content...etc, are updated automatically)
7. can convert all docs to any format (html, txt, doc, pdf...) at one time with just one click (thus people can download the whole thing in one file if they wish); version history/management
8. can work offline is a plus

I don't know if such kind of software exist. I'm not sure docBook is anything close to it and so I asked...still, no one is telling me how docBook works or what's "SGML document type definition"... no one knows?

PS. Actually I'm inspired by this page you sent me to, which is clean and organized. I think they mentioned docBook somewhere (but I can't find it now) and that led me to do a search of that software.
Last edited by puppian on Sun 16 Oct 2005, 07:02, edited 2 times in total.
[url=http://puppylinux.org]Puppylinux.org - Community home page of Puppy Linux[/url] hosted by Barry (creator of Puppy), created and maintained by the [url=http://puppylinux.org/user/readarticle.php?article_id=8]Puppy Linux Foundation[/url] since 2005

User avatar
Lobster
Official Crustacean
Posts: 15522
Joined: Wed 04 May 2005, 06:06
Location: Paradox Realm
Contact:

#9 Post by Lobster »

m m m . . .
use plain text
add to (practically anything - Open Office, wiki, blog, forum)

to output as HTML - add text to open office or composer (in Mozilla)

add a pic

save as HTML

Document done - to oganise - create an index.html or home page

8)
Puppy Raspup 8.2Final 8)
Puppy Links Page http://www.smokey01.com/bruceb/puppy.html :D

User avatar
puppian
Posts: 537
Joined: Tue 19 Jul 2005, 03:58
Location: PuppyLand
Contact:

#10 Post by puppian »

very prompt reply lob :lol:

this works if there's only one or two editors...but things may become complex when we've a lot of editors :)
puppian wrote:...pages are well-organized and all pages look the same/similar in style, though they are written by different people...
let's see what the others think :evil:

(or they just don't care? if so your approach maybe the best ;))
[url=http://puppylinux.org]Puppylinux.org - Community home page of Puppy Linux[/url] hosted by Barry (creator of Puppy), created and maintained by the [url=http://puppylinux.org/user/readarticle.php?article_id=8]Puppy Linux Foundation[/url] since 2005

raffy
Posts: 4798
Joined: Wed 25 May 2005, 12:20
Location: Manila

Still a Wiki

#11 Post by raffy »

What your latest posts describe is a Wiki done with minimal page formatting (that is, the writing is in plain text). Pictures and links are easily added to the Wiki, and multiple editors of a page is possible.

HTML is still close to being plain text as the HTML markup can be easily stripped off.

The funny development in Wiki (see MediaWiki) is the use of WYSIWYG features. WYSIWYG editors output HTML, so why bother with Wiki formatting at all when WYSIWYG outputs HTML directly?

As Puppian will now know, Wikka allows you to use HTML, but you have to ADD markup to do it. Ergo, just use that markup and you're using HTML. The funny thing there is, why use another markup just to use HTML?

Lobster, the page I showed is HTML done in WYSIWYG editor (suitable for Mozilla). If an author maintains a page like this, he can keep it updated, or users add comments that are appended to the same page.

Authors can be given access to a folder where s/he outputs pages and submits links (of pages) to a human editor who organizes these into a Table of Contents or index.

I think I should provide an example folder for people to play with. Will be back here when that is ready...

EDIT: Here is the link http://www.ph-islands.net/example/
Last edited by raffy on Mon 17 Oct 2005, 13:10, edited 1 time in total.

User avatar
Lobster
Official Crustacean
Posts: 15522
Joined: Wed 04 May 2005, 06:06
Location: Paradox Realm
Contact:

Re: Still a Wiki

#12 Post by Lobster »

raffy wrote: As Puppian will now know, Wikka allows you to use HTML, but you have to ADD markup to do it. Ergo, just use that markup and you're using HTML. The funny thing there is, why use another markup just to use HTML?
Exactly so.
We are learning. Puppian is doing some great pages - but they are in HTML (and that is OK)
:)

The point of a wikka is ease of use so the closer to plain text the easier.

Puppian was experimenting with HTML in pages because he knows HTML as do I but not everbody does.

The below (though it might not seem so to some) is the "simple" code of a wiki (and each type of wiki uses slightly different code) It is very simple to use if you have a history of HTML usage.

Code: Select all

{{color hex="#DD0000" text=". . . Download . . . "}}[[KrazyPuppy PUPPY 1.0.5]]{{color hex="#DD0000" text=" . . . Download . . ."}}
**[[LanguageSupport Language support:]]** [[GermanLanguage Deutsch]] [[SpanishLanguage Espanole]] [[FrenchLanguage Francais]] [[JapaneseLanguage Japanese]] [[PortugeseLanguage Portugese]] 
{{image class="left" url="http://tinypic.com/b4d9tv.gif" link="http://www.goosee.com/puppy/amy/index.html" alt="The Real Puppy" title="The Real Puppy"}}
contrast that with a simpler page
http://www.goosee.com/puppy/wikka/ReviewsPuppy
(that is picture reference at top and text)

Code: Select all

{{image url="http://tinypic.com/5zdvuo" }}

I have several live Linux distros --- Damn Small, ""MuLinux"", ""ZipSlack"", etc. A few days ago I had a mishap and lost the password to my Linux partition. I know how to get around that but needed to get into the filesystem to do it. I first tried DSL because that's mentioned in connection to emergencies so often. Maybe it was my fault, but Damn Small would not let me into my system. I popped the Pup into my cd tray and booted up and, sure enough, the accommodating canine let me go into my Linux files and make necessary changes. I like this little guy better than any Linux I've used off a removable disk. Bravo! Good dog!
-- ""CharleMax"" (2005-08-12 13:36:02)
Contrast that with HTML on a page - where things start to become too complex . . .

The great thing about wiki
is all styles and possibilities are welcome

8)
Puppy Raspup 8.2Final 8)
Puppy Links Page http://www.smokey01.com/bruceb/puppy.html :D

puppian_guest

#13 Post by puppian_guest »

You are right raffy, what I decribe is close to a wiki, but there're some crucial features that wiki lack, e.g.

2. templates; the user only have to imput the content in an input box (much like posting in this forum), but there would be more than one input box. so the content of each box becomes a section of the output page (similar to 'section-editing' in Media wiki?); this way only few formatting rules are needed (only BBCode perhaps); and editing is done mostly in plain text

3. user can select which catergory a page go to after creating it with just one click

4. table of content / sitemap and index are generated automatically (again with just one click Smile)

5. output files are easy to navigate (with menu/sidebar/anchor, etc)

7. can convert all docs to any format (html, txt, doc, pdf...) at one time with just one click (thus people can download the whole thing in one file if they wish); version history/management

8. can work offline is a plus

Bascally a good system / software like that should allow the user to choose whether they want to edit with html or WYSIWYG (like Blogger :))

The good thing of templates mentioned above is that the layout is controlled by the template and won't can be kept consistent with many editors (that may not be good for a web site, but will be good for formal documentation).

I haven't used anything (wik/blog) that satisfies all the criteria listed, perhaps CMS (Content Management System) can do better:
http://en.wikipedia.org/wiki/Content_management_system

Guest

#14 Post by Guest »

>>The good thing of templates mentioned above is that the layout is controlled by the template and won't can be kept consistent with many editors....

In other words, the 'complex' html part is done by the template already. The user only need to enter the content part, so can focus on it ;)

User avatar
puppian
Posts: 537
Joined: Tue 19 Jul 2005, 03:58
Location: PuppyLand
Contact:

#15 Post by puppian »

In fact I think the 'example folder' raffy mentioned is some form of CMS (it says My Easy CMS in the title ;)). How did you do that raffy? Can other features (templates, categoriztion and table of content...etc) be installed too? If so that would be cool 8)

(Btw is there any CMS that allow the use of formatting rules like that in wiki? If so that would be Very cool 8) 8))

Here is a popular one; feature list (many professional sites use it). There're lots of other choices (CMS and more) at hotscripts.com too.
Lobster wrote:The great thing about wiki
is all styles and possibilities are welcome
I agree and I like our wiki a lot, so wiki should be there of course :)

Edit: just come across php.net incidentally and now I know more about docBook
http://www.php.net/manual/howto/chapter-docbook.html
http://www.php.net/manual/howto/part-ge ... arted.html
http://www.php.net/manual/howto/
"DocBook is a very popular set of tags for describing books, articles, and other prose documents, particularly technical documentation. DocBook is defined using the native DTD syntax of SGML and XML.... Simply this means, that writing a DocBook file is no more, than writing a text file, ..."

:oops: It's not a software at all! The whole thing looks a bit complex (to me). SGML/ XML is something new to me too... but I'm sure that they make sense to many smart puppies :)
[url=http://puppylinux.org]Puppylinux.org - Community home page of Puppy Linux[/url] hosted by Barry (creator of Puppy), created and maintained by the [url=http://puppylinux.org/user/readarticle.php?article_id=8]Puppy Linux Foundation[/url] since 2005

raffy
Posts: 4798
Joined: Wed 25 May 2005, 12:20
Location: Manila

What is

#16 Post by raffy »

Maybe you can help me describe that :)

What I did is a simple set of scripts for writing HTML pages, with the file name acting as automatic menu. Editing is WYSIWYG, and you can in fact choose the editors (see the Making Help with HTML page for the example editors), although I have put there TinyMCE because of its advanced features (but is very strict with formatting and is quite slow on old machines).

I did an example use of a category page, although the scripts are not really expecting categorization. A static page with frames can handle that work, though. Say, authors email you (Puppian) with URL to new HTML pages and you collect these links in that multi-frames page :idea:

Post Reply