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?

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 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?_________________Puppylinux.org - Community home page of Puppy Linux hosted by Barry (creator of Puppy), created and maintained by the Puppy Linux Foundation since 2005

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

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._________________Puppylinux.org - Community home page of Puppy Linux hosted by Barry (creator of Puppy), created and maintained by the Puppy Linux Foundation since 2005Last edited by puppian on Sun 16 Oct 2005, 03:02; edited 2 times in total

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, 09:10; edited 1 time in total

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.

contrast that with a simpler page
http://www.goosee.com/puppy/wikka/ReviewsPuppy
(that is picture reference at top and text)

Code:

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

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

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

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

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-getting-started.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, ..."

You cannot post new topics in this forumYou cannot reply to topics in this forumYou cannot edit your posts in this forumYou cannot delete your posts in this forumYou cannot vote in polls in this forumYou cannot attach files in this forumYou can download files in this forum