Subject: Windows CHM format for the documents

From: <[email-masked]>
Date: Mon, 8 Sep 2003 03:37:00 +0300

Hello,

As Postgres is now going native to Windows platform, many people will
probably want a CHM format (HTML Help) of the manuals.

I have made one from the User Guide, and I can make those from the other
manuals too if people would like to see more of them. The CHM is at address
http://www.visiomode.com/help/pg/

There is also a web viewing capability at address
http://www.visiomode.com/help/help/starthelp.php?doc=1&grp=5

Further, that document (and others) can be edited also in the web by the
software that I've made the CHM with. You can test the editing at address.
http://www.visiomode.com/help/help/
Username: pg
password: 1a2s3d
- The wysiwyg editor requires IE. Use "plain" editor (set from
File->preferences) if you don't have IE.

If you want to take that software in to use, I can give a license of it to
PostgreSQL community. In any case, I can create CHMs for you if you want.

Thanks,
Ilkka

--
Ilkka Huotari
http://www.visiomode.com/

---

From: Bruce Momjian <[email-masked]>
Date: Sun, 7 Sep 2003 23:00:04 -0400 (EDT)

> PostgreSQL community. In any case, I can create CHMs for you if you want.

I have added that to the Win32 project page:

	http://momjian.postgresql.org/main/writings/pgsql/win32.html

-- 
  Bruce Momjian                        |  http://candle.pha.pa.us
  [email-masked]               |  (610) 359-1001
  +  If your life is a hard drive,     |  13 Roberts Road
  +  Christ can be your backup.        |  Newtown Square, Pennsylvania 19073

---

From: Darko Prenosil <[email-masked]>
Date: Mon, 8 Sep 2003 09:26:43 +0200

> > probably want a CHM format (HTML Help) of the manuals.
Bruce, we have done that before a month for pgAdmin for entire postgresql 
documentation. Please contact Andreas - no need to do it again !

Regards !

---

From: Andreas Pflug <[email-masked]>
Date: Mon, 08 Sep 2003 12:05:43 +0200

>documentation. Please contact Andreas - no need to do it again !

What we *not* have done so far is extracting keywords from the doc. It's 
not easy for us pgadminers keeping up-to-date with the doc, but it's 
doable (we need to notice added/deleted pages to update the contents), 
but maintaining the keywords is probably beyond our capabilities.

Regards,
Andreas

---

From: Darko Prenosil <[email-masked]>
Date: Mon, 8 Sep 2003 13:12:45 +0200

> but maintaining the keywords is probably beyond our capabilities.
Extracting words from docs would be difficult, but if keywords from 
"bookindex.html" are god enough - it can be done. 

Regards !

---

From: <[email-masked]>
Date: Tue, 9 Sep 2003 00:07:25 +0300

Ok,

I made a CHM that contains all those documents (6 of them) .. It's also in
http://www.visiomode.com/help/pg/

I would be so happy if you wanted to take my software for the editing
process .. :) But in any case, if there is use for those CHMs, that would be
great too.

Ilkka

----- Original Message ----- 
From: "Darko Prenosil" <[email-masked]>
To: "Bruce Momjian" <[email-masked]>; <[email-masked]>
Cc: <[email-masked]>; "PostgreSQL Win32 port list"
<[email-masked]>
Sent: Monday, September 08, 2003 10:26 AM
Subject: Re: [pgsql-hackers-win32] [DOCS] Windows CHM format for the
documents

---

From: Christopher Browne <[email-masked]>
Date: Mon, 08 Sep 2003 17:18:53 -0400

> http://www.visiomode.com/help/pg/

Cool!

> I would be so happy if you wanted to take my software for the
> editing process .. :) But in any case, if there is use for those
> CHMs, that would be great too.

The source format of DocBook SGML is a whole lot more widely usable on
most of the platforms on which PostgreSQL runs, so I would hope that
your software has some sort of "batch mode" that can accept HTML (or
something like HTML) and transform it into .chm files.  The preference
would only be likely to swing in your direction if PostgreSQL became
more prevalent on Windows than on Unix.
-- 
"cbbrowne","@","ntlug.org"
http://cbbrowne.com/info/advocacy.html
"Seriously, I think you really need to find out who took your sense of
humor, beat the crap out of  him, and take it back. It's getting old."
-- Michael J Ash <[email-masked]>, on comp.lang.objective-c

---

From: <[email-masked]>
Date: Wed, 10 Sep 2003 04:53:02 +0300

> more prevalent on Windows than on Unix.

Yes, exactly like that, it has the ability to import documents from many
different formats. There is an PHP API for importing documents into the
"internal format" (=database), and it's quite straightforward to write
plugins for different types of documents. I just made a plugin for the
Postgres documents a couple of days ago, it eats the HTML that is in
PostgreSQL site. Also it has the ability to import long html files.

Then, the software can "export" the documents in different formats as well.
The formats supported are:
- Long HTML files
- PDF (with a table of contents)
- CHM
- More can be written, ie. if you want to offer the documents the same way
as they are now on the web, that is not a big task.

Also there is the possibility to view on the web while they are in the
"internal" format.

As Postgres documentation are most probably written in quite a (highly?)
collaborative way, I think my software would be good to help you to maintain
those documents.I think Andreas just mentioned that maintaing is a bit
difficult, and this might help you. There is one type of multiauthoring
support implemented which means:
- An instructive chapter locking
- The "editing history" can be seen for every "topic", ie. who as edited a
topic and when.

What comes to keywords discussed, they can be maintained in the "index"
section. Keywords can also be read from the file by a plugin.

I'm not sure if it would be a bad thing to give up DocBook, but I cannot see
anything but benefits from using this other type of document development...

This software is now "almost ready", so it lacks small things that will be
done a in near future. I'm not asking money naturally (I shouldn't even
mention this) but to see my software in action would be enough.

A couple of urls:

Editing:
http://www.visiomode.com/help/help/
username: pg
password: 1a2s3d
(don't try to import pg documents now, please, but instead try to edit the
current one)

Viewing:

Thanks,
Ilkka

---

From: Peter Eisentraut <[email-masked]>
Date: Wed, 10 Sep 2003 19:29:12 +0200 (CEST)

> anything but benefits from using this other type of document development...

I don't see any advantages that this would have over the current setup.

-- 
Peter Eisentraut   [email-masked]

---

From: Jeroen Ruigrok/asmodai <[email-masked]>
Date: Wed, 10 Sep 2003 19:43:37 +0200

>anything but benefits from using this other type of document development...

It would be.  Editing simple text files is less cumbersome for a
technical writer than it is to do everything on the database/front-end.

(And I work as a professional technical writer in case someone cared.)

-- 
Jeroen Ruigrok van der Werven <asmodai(at)wxs.nl> / asmodai
PGP fingerprint: 2D92 980E 45FE 2C28 9DB7  9D88 97E6 839B 2EAC 625B
http://www.tendra.org/   | http://www.in-nomine.org/~asmodai/diary/
A woman either loves or hates; she knows no medium. - Publilius

---

From: Jeroen Ruigrok/asmodai <[email-masked]>
Date: Wed, 10 Sep 2003 19:45:31 +0200

>	http://momjian.postgresql.org/main/writings/pgsql/win32.html

If you move to DocBook/XML and use XSL(T) you can use the htmlhelp.xsl
stylesheet and go directly to CHM from XML files.

-- 
Jeroen Ruigrok van der Werven <asmodai(at)wxs.nl> / asmodai
PGP fingerprint: 2D92 980E 45FE 2C28 9DB7  9D88 97E6 839B 2EAC 625B
http://www.tendra.org/   | http://www.in-nomine.org/~asmodai/diary/
To desire immortality is to desire the eternal perpetuation of a great
mistake...

---

From: <[email-masked]>
Date: Wed, 10 Sep 2003 21:30:36 +0300

> (And I work as a professional technical writer in case someone cared.)

Yes that makes sense...

I'll come up with something to make editing easier. Probably the whole stuff
would be in the editor at the same time..

Thanks for the feedback.

Ilkka

---

From: Christopher Browne <[email-masked]>
Date: Wed, 10 Sep 2003 16:33:37 -0400

> anything but benefits from using this other type of document development...

I cannot see anything but problems from using this.

- The current usage allows people to work on documents as files, using
  whatever editing tools they like.  With your "server software," that
  is lost.

- Current usage uses CVS to manage changes.  This allows changes to be
  looked at and approved/rejected/modified.  I haven't any idea if
  your system uses text files in behind, it sounds like not.

- Current usage does not mandate that anyone have a synchronous
  connection to a central server that becomes bottleneck / vulnerable
  point.  

The apparent "benefit" of your tool is that it provides a tool with a
user interface that slavishly follows the Windows "CHM file" viewer.
That may be an advantage to those that want to slavishly follow
Windows development/deployment "standards," but I daresay you're NOT
in a community that is particularly interested in that sort of thing.
-- 
wm(X,Y):-write(X),write('@'),write(Y). wm('aa454','freenet.carleton.ca').
http://www3.sympatico.ca/cbbrowne/nonrdbms.html
Sturgeon's Law: 90% of *EVERYTHING* is crud.

---

From: <[email-masked]>
Date: Sun, 14 Sep 2003 03:03:51 +0300

>   whatever editing tools they like.  With your "server software," that

Yes, it is harder to use any tool for editing (though not
impossible,copy/paste could be used :-).

There are benefits from using the same tool too - the output will probably
look the same throughout the document. The central server idea emphasizes
this even more I think ... and the programmatically (sp?) :-)

>   your system uses text files in behind, it sounds like not.

Creating some of the CVS features wouldn't be a problem at all. For example
storing certain situations (labeling) would be a good idea (of course the
current backuping could be used for this as well).

>   connection to a central server that becomes bottleneck / vulnerable

Yes, well, nowadays most people have fixed lines (in the future more so), I
wouldn't count this a big drawback.

> in a community that is particularly interested in that sort of thing.

I'm far away from favoring any particular OS. Personally I have done more
Unix/Linux development than Windows. But as long as this shouldn't be an OS
war forum, I think all OSs pretty much suck at some things, and are good at
others.

CHM is only one choice for output, and besides it's not only for Windows.
http://xchm.sourceforge.net/ there's a CHM viewer for Linux. There are more
similar kinds of viewers with slightly different file format, but they do
the same. I think that CHM has its advantages and I like using them.

I'm fine if you want to use your tools, and sorry if I bothered you...It was
just an option that I presented and you have given some good feedback of it.

Ilkka