Nathan Kopp wrote:
> 
> What would be the desired format for MegaPov documentation for Windows and
> Unix?
> 
> Available formats to choose from:
> 
> WordPerfect
> MS Word 97
> MS Word (simple, read by WordPad)
> PostScript
> PDF (only if I can generate it with free tools)
> HTML (export from MS Word)
> Some other format that I could easily generate from a MS Word file using
> free tools.
> 
> (Sorry, but I don't have any tools to generate HLP files for Windows.)
> 
> -Nathan

I use Unix and I prefer ps/pdf for printed documentation, and CLEAN (ie.
not word-generated) HTML for browsing.

-- 

      __  __ __  __  _
|  | /  \  /  / |_  /  |/
\/\/ \__/ /_ /_ |__ \_ |\

Post a reply to this message

Ron Parker <ron### [at] povrayorg> wrote...
>
> I use Windows and Unix, and I'd like DocBook because you can easily
transform
> it into PDF, HTML, RTF, TeX, and lots of other formats.

Ron,

I develop on a Windows computer.  Are there free tools available for me to
use easily DocBook?  Also, the Smellenbergh brothers work primarily on the
Mac, so free Mac tools are necessary as well.

If that is possible, could you please point me a the general direction to
get started.  I've been to a few websites about DocBook, SGML, and XML, and
they all provided far too much information to be useful for me (I don't have
three years to learn a new tool for creating the MegaPov 0.4 documentation.)
;-)  You can email me with your reply or just post it here.  I'll get it
either way.

Otherwise, we'll probably end up using HTML as the primary format and
converting from that to other formats.

-Nathan

Post a reply to this message

Jon A. Cruz wrote in message <388BA0BB.67F6720A@geocities.com>...
>Nathan Kopp wrote:


>> (Sorry, but I don't have any tools to generate HLP files for Windows.)
>>
>> -Nathan
>
>Hmmm. If you sign up for the free MSDN membership, you might get free
access
>to their help compiler. It's worth looking into.
>

I doubt it.  MS is now pushing HTML-Help, and, quite honestly, I have yet to
see a good
HTMLHelp file.  (The first HTML output I ever saw from MS Word was probably
better!)

Brendt

Post a reply to this message

Ron Parker wrote:
> 
> On Sun, 23 Jan 2000 15:35:55 -0500, Nathan Kopp wrote:
> >
> >What would be the desired format for MegaPov documentation for Windows and
> >Unix?
> >Some other format that I could easily generate from a MS Word file using
> >free tools.
> 
> DocBook!  DocBook!

I second that.

-Mark Gordon

Post a reply to this message

Hi Nathan,
so I guess my links confused you, so I take the chance and answer your
question to Ron :-)

As I found out, jade is available for Windows, and I would think, that
someone could get it running on Mac. I am not so much into mac, so don't
ask me for tools.

As of starting with docbook:
Use the definite docbook reference at http://www.docbook.org and an
editor that will support sgml (xml) editing.

I use xemacs and psgml-mode, which are available for windows as well.
But any editor with a DESCENT support will do.

Such an editor will give you some grammar checking based on the DTD you
specify for the file. And then you don't have the choice of some 100
elements, but just about 10-20, and the one you want is generally quite
obvious. psgml gives you a context menu with all valid elements at the
point of the cursor, so that is simple. And you can't do wrong grammar
that way.

So taking good tools, you should be able to get going with docbook in
just a day.

So look for DTD parsing editors with context sensitive element
insertion.

Axel

Post a reply to this message

On Mon, 24 Jan 2000 17:59:48 -0500, Nathan Kopp wrote:
>
>Ron Parker <ron### [at] povrayorg> wrote...
>>
>> I use Windows and Unix, and I'd like DocBook because you can easily
>transform
>> it into PDF, HTML, RTF, TeX, and lots of other formats.
>
>Ron,
>
>I develop on a Windows computer.  Are there free tools available for me to
>use easily DocBook?  Also, the Smellenbergh brothers work primarily on the
>Mac, so free Mac tools are necessary as well.

I'm still looking for a good SGML editor.  FrameMaker+SGML looks really nice,
but it's horribly expensive.  WordPerfect has an SGML mode, too.  I have WP
at the office, and someday I'll get around to checking out its SGML support.
The best editing solution I've found is psgml-mode for emacs, which is free,
but if you're not used to emacs you might not like it.  There are commercial
XML editors, such as XMetal.  There's also XED, 
http://www.cogsci.ed.ac.uk/~ht/xed.html which you might find less intimidating 
than psgml-mode.  A Mac version isn't currently available, but is in 
development.  Another browser/editor is jumbo, http://xml-cml.org/jumbo/ which 
is in Java and available for the Mac.  SGML/XML itself is a lot like HTML, so 
you shouldn't have any trouble editing it by hand.  The main difference you'll 
find is that in DocBook, you tag things by function rather than by appearance 
(like HTML was supposed to work.)

The W3C has a bunch of links to XML software, some of which is written in 
Java.  See http://www.w3.org/XML/#software .  Another good list of XML and
SGML tools is at http://209.41.82.30/cover/publicSW.html .

Jade apparently isn't available for the Mac, but it is available in source
form so presumably one could build it for the Mac.  Failing that, there is
YADE, written in Java.  Jade and YADE are DSSSL stylesheet processors, used
to convert DocBook to other formats.  It's possible that only one of you
would need to be able to use them.

>Otherwise, we'll probably end up using HTML as the primary format and
>converting from that to other formats.

If you'll be using hand-edited HTML, you should just make the leap to DocBook,
because it's more powerful and easier to convert to other formats.

-- 
These are my opinions.  I do NOT speak for the POV-Team.
The superpatch: http://www2.fwi.com/~parkerr/superpatch/
My other stuff: http://www2.fwi.com/~parkerr/traces.html

Post a reply to this message

"Nathan Kopp" <Nat### [at] Koppcom> writes:

> Nathan Kopp <Nat### [at] Koppcom> wrote ...
> >
> > What would be the desired format for MegaPov documentation for Windows and
> > Unix?
> >
> 
> I guess I worded that poorly.  I was hoping for answers like:
>   "I use unix, and I'd like _____."
> or
>   "I use Windows, and I'd like ______."
> 

I use unix, and I'd like HTML for online browsing (and perhaps gzipped
or zipped Postscript for printing).

Thomas

-- 
http://thomas.willhalm.de/ (includes pgp key)

Post a reply to this message

Nathan Kopp schrieb:

> I guess I worded that poorly.  I was hoping for answers like:
>   "I use unix, and I'd like _____."
> or
>   "I use Windows, and I'd like ______."

I use Unix, and almost everything there can be converted into
almost erverything else (if it is standard compliant and does
not involve the violation of the second law of thermodynamics,
as e.g. back from PS to HTML).

Since it seems that you write (or even already wrote part of)
the manual in Word, the situation is nontrivial: Everything
that Word creates is either proprietary (.doc, .hlp with
additional tools) or noncompliant (broken .ps, broken .html).

Something like SGML or XML might be optimal for the world,
since people who have tools can convert it into everything else
(AFAIK including .rtf, opening the way into the evil empire)
and put on their FTP servers.

OTOH, forcing you to use SGML would cost your time, thus
depriving us all of more cool patches to POV.

A compromise would be to use what you are familiar with,
and publish it as RTF (for those who want to manipulate
it) and HTML for online reading. People who want to print
it can use the export function of the browser (or you just
publish a copy in .ps as well).

Btw., the .ps from MS stuff can be made compliant using

      gs -sDEVICE=pswrite -other_options ...

(but this fixes the resolution and increases the filesize, and
seems to impair quality).

If you can publish only one version, HTML might be optimal
(it can be converted to .ps using browsers and printed,
if necessary).

Ralf

Post a reply to this message

rmu### [at] t-onlinede (Ralf Muschall) wrote in <388E4B7E.2DAE21BC@t-
online.de>:

>Nathan Kopp schrieb:
>
>> I guess I worded that poorly.  I was hoping for answers like:
>>   "I use unix, and I'd like _____."
>> or
>>   "I use Windows, and I'd like ______."

    	I use Windows, Amiga, Lynix and Mac.  HTML would be my choice above 
all others!  <smile>  I really don't see how HTML is a bad choice for 
printing.  All it takes is a bit of pre-planning; put each page in a fixed 
width table, so the format when printed will look exactly like the format 
on screen, and make sure each page will fit on a printed page.  Use this 
template for every page, and all you have to worry about is what to write, 
not how to format it.
    	Hyperlinks are, by far, more important to me than pretty printouts 
anyway.  If you want to get fancy, some simple scripts can be created to do 
searches on the HTML pages that will work on any modern browser.  But a 
well thought out contents page is fine.

Rich

Post a reply to this message

On 26 Jan 2000 13:12:20 -0500, Rich wrote:
>All it takes is a bit of pre-planning; put each page in a fixed 
>width table, so the format when printed will look exactly like the format 
>on screen, and make sure each page will fit on a printed page.  

Dear God, no!  What of the different screen resolutions in use around here?
Many of us run at 800x600, but many others run at 1600x1200.  No single 
fixed width will work well with both sizes.

PDF is the thing to use if you're going for printed material and you insist
on a layout-based format.  It supports hyperlinks, it is always the same 
layout, and it has good print quality.  Unfortunately, Acrobat's not available
for the Amiga.

I still contend that a good content-based format (DocBook, TexInfo) would 
be better than any layout-based format (modern HTML, PS, PDF, Word) simply
because it can be converted to lots of different layout-based formats and
subformats (e.g. different stylesheets for different HTML usage.)  Good 
converters also support automatic TOC and index generation.

If nobody else does it, I'll make an attempt to write a template for Word
for DocBook creation.

-- 
These are my opinions.  I do NOT speak for the POV-Team.
The superpatch: http://www2.fwi.com/~parkerr/superpatch/
My other stuff: http://www2.fwi.com/~parkerr/traces.html

Post a reply to this message