Puppy Linux Discussion Forum Forum Index Puppy Linux Discussion Forum
Puppy HOME page : puppylinux.com
"THE" alternative forum : puppylinux.info
 
 FAQFAQ   SearchSearch   MemberlistMemberlist   UsergroupsUsergroups   RegisterRegister 
 ProfileProfile   Log in to check your private messagesLog in to check your private messages   Log inLog in 

The time now is Thu 20 Nov 2014, 17:20
All times are UTC - 4
 Forum index » Taking the Puppy out for a walk » Puppy Power
Has anyone used DocBook? (for documentation)
Moderators: Flash, JohnMurga
Post new topic   Reply to topic View previous topic :: View next topic
Page 1 of 2 [16 Posts]   Goto page: 1, 2 Next
Author Message
puppian


Joined: 18 Jul 2005
Posts: 538
Location: PuppyLand

PostPosted: Thu 13 Oct 2005, 16:38    Post subject:  Has anyone used DocBook? (for documentation)  

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/

_________________
Puppylinux.org - Community home page of Puppy Linux hosted by Barry (creator of Puppy), created and maintained by the Puppy Linux Foundation since 2005

Last edited by puppian on Mon 17 Oct 2005, 10:26; edited 3 times in total
Back to top
View user's profile Send private message Visit poster's website 
puppian


Joined: 18 Jul 2005
Posts: 538
Location: PuppyLand

PostPosted: Fri 14 Oct 2005, 10:08    Post subject:  

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.

_________________
Puppylinux.org - Community home page of Puppy Linux hosted by Barry (creator of Puppy), created and maintained by the Puppy Linux Foundation since 2005
Back to top
View user's profile Send private message Visit poster's website 
Ian
Official Dog Handler


Joined: 04 May 2005
Posts: 1237
Location: Queensland

PostPosted: Fri 14 Oct 2005, 21:11    Post subject:  

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.
Back to top
View user's profile Send private message 
puppian


Joined: 18 Jul 2005
Posts: 538
Location: PuppyLand

PostPosted: Sat 15 Oct 2005, 12:52    Post subject:  

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 Smile) 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 Embarassed 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 Sad

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
Back to top
View user's profile Send private message Visit poster's website 
Lobster
Official Crustacean


Joined: 04 May 2005
Posts: 15117
Location: Paradox Realm

PostPosted: Sat 15 Oct 2005, 13:56    Post subject:  

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 WIKI
Back to top
View user's profile Send private message Visit poster's website 
raffy

Joined: 25 May 2005
Posts: 4796
Location: Manila

PostPosted: Sat 15 Oct 2005, 18:43    Post subject: Quick HTML page  

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, 09:02; edited 1 time in total
Back to top
View user's profile Send private message 
Lobster
Official Crustacean


Joined: 04 May 2005
Posts: 15117
Location: Paradox Realm

PostPosted: Sat 15 Oct 2005, 23:41    Post subject:  

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 WIKI
Back to top
View user's profile Send private message Visit poster's website 
puppian


Joined: 18 Jul 2005
Posts: 538
Location: PuppyLand

PostPosted: Sun 16 Oct 2005, 02:32    Post subject:  

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 Cool

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 Wink)

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 Smile)
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 2005

Last edited by puppian on Sun 16 Oct 2005, 03:02; edited 2 times in total
Back to top
View user's profile Send private message Visit poster's website 
Lobster
Official Crustacean


Joined: 04 May 2005
Posts: 15117
Location: Paradox Realm

PostPosted: Sun 16 Oct 2005, 02:38    Post subject:  

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

Cool

_________________
Puppy WIKI
Back to top
View user's profile Send private message Visit poster's website 
puppian


Joined: 18 Jul 2005
Posts: 538
Location: PuppyLand

PostPosted: Sun 16 Oct 2005, 02:55    Post subject:  

very prompt reply lob Laughing

this works if there's only one or two editors...but things may become complex when we've a lot of editors Smile
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 Very Mad

(or they just don't care? if so your approach maybe the best Wink)

_________________
Puppylinux.org - Community home page of Puppy Linux hosted by Barry (creator of Puppy), created and maintained by the Puppy Linux Foundation since 2005
Back to top
View user's profile Send private message Visit poster's website 
raffy

Joined: 25 May 2005
Posts: 4796
Location: Manila

PostPosted: Sun 16 Oct 2005, 19:18    Post subject: Still a Wiki  

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
Back to top
View user's profile Send private message 
Lobster
Official Crustacean


Joined: 04 May 2005
Posts: 15117
Location: Paradox Realm

PostPosted: Sun 16 Oct 2005, 20:49    Post subject: Re: Still a Wiki  

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)
Smile

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

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

Cool

_________________
Puppy WIKI
Back to top
View user's profile Send private message Visit poster's website 
puppian_guest
Guest


PostPosted: Mon 17 Oct 2005, 01:15    Post subject:  

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 Smile)

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
Back to top
Guest
Guest


PostPosted: Mon 17 Oct 2005, 01:19    Post subject:  

>>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 Wink
Back to top
puppian


Joined: 18 Jul 2005
Posts: 538
Location: PuppyLand

PostPosted: Mon 17 Oct 2005, 01:55    Post subject:  

In fact I think the 'example folder' raffy mentioned is some form of CMS (it says My Easy CMS in the title Wink). 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 Cool

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

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 Smile

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

Embarassed 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 Smile

_________________
Puppylinux.org - Community home page of Puppy Linux hosted by Barry (creator of Puppy), created and maintained by the Puppy Linux Foundation since 2005
Back to top
View user's profile Send private message Visit poster's website 
Display posts from previous:   Sort by:   
Page 1 of 2 [16 Posts]   Goto page: 1, 2 Next
Post new topic   Reply to topic View previous topic :: View next topic
 Forum index » Taking the Puppy out for a walk » Puppy Power
Jump to:  

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


Powered by phpBB © 2001, 2005 phpBB Group
[ Time: 0.1082s ][ Queries: 11 (0.0044s) ][ GZIP on ]