This is something i had in mind for some time and i wanted to suggest it
before the release of final Povray 3.5 when everyone will start working on
custom versions again.

I noticed that the various unofficial versions have documentation of very
different form. For example:  

Megapov has HTML and Windows help format documentation
PovMan comes with HTML, but the clothray part in a separate file of
different form
Megapov Plus has several plain text files
MLPov a website with description and examples

I think it would be good if we could introduce some standards for future
patch documentation, Megapov already merges the documentations of various
patches in one file, especially the 'Megapov + X' patches would profit
from extending this to a general patch documentation system.  

My suggestion would be to ask the patch authors to supply documentation in
basic HTML and to develop a script that generates an index file from all
the documentation parts relevant for the distribution.  Authors of new
patches who use already existing unofficial versions as a basis would only
need to put together the different documentation parts, generate the index
and put everything in the distribution and the user would have all
necessary documentation accessible through one index file.  There could
also be hooks in the Windows and Mac GUIs to access this file from within
the program.

This is only meant as a basis for further discussion, it would be
interesting to know:

- whether patch authors think this is feasible and useful
- if other methods would be better
- if such a system is created how it should be established (maybe
something like official patch documentation guidelines?)

Opinions?


Christoph

-- 
POV-Ray tutorials, IsoWood include,                 
TransSkin and more: http://www.tu-bs.de/~y0013390/  
Last updated 14 Apr. 2002 _____./\/^>_*_<^\/\.______

Post a reply to this message

Christoph Hormann wrote:
[snip]
 > This is only meant as a basis for further discussion, it would be
 > interesting to know:
 >
 > - whether patch authors think this is feasible and useful

Yes, I guess that basic HTML should be portable enough and cover 99.9 %
of POV-Ray patch users.

 > - if other methods would be better
IMO there is no other methods, which were so portable as HTML (plain 
text perhaps, but it does not allow formatting/colouring/easy displaying 
of images and even text files are different for *X/Mac/Windows)

 > - if such a system is created how
 > it should be established (maybe something like official patch
 > documentation guidelines?)

I guess You meant "official unoffical patch's doc..." (or should it be 
"unofficial patch's offical doc..." :-)

 > Opinions?

Writing documentation is hardest part of patch creation  :-), so if 
there are guidelines/templates, then it would be great help.
Easiest would be to put each patch documentation to separate directory 
and require, that patch-specific index file is in parent directory. This 
way updating various patches documentation would be easy (just replace 
directory and index file). Main documentation would be created by having 
links to separate patches index files (not very user-friendly) or by 
copying patch-specific index files contents to one document (requires 
more work, but has better usability). In latter case it should be agreed 
general layout of index file, so that every part has similar appearance 
(e.g. patch name with header 3, subchapters with header 4, etc).

Post a reply to this message

I think that such a system would be a great idea. Have you given any thought
as to how you would implement it? www.wxwindows.org has something (wxHTML),
which might help get things started.

Post a reply to this message

Vahur Krouverk wrote:
> 
> [...]
> Writing documentation is hardest part of patch creation  :-), so if
> there are guidelines/templates, then it would be great help.
> Easiest would be to put each patch documentation to separate directory
> and require, that patch-specific index file is in parent directory. This
> way updating various patches documentation would be easy (just replace
> directory and index file). Main documentation would be created by having
> links to separate patches index files (not very user-friendly) or by
> copying patch-specific index files contents to one document (requires
> more work, but has better usability). In latter case it should be agreed
> general layout of index file, so that every part has similar appearance
> (e.g. patch name with header 3, subchapters with header 4, etc).

This is about the concept i have in mind, but i would not force a separate
index file for each patch, especially for small additions this seems
rather complicated and would not improve usability.  Instead it could be
agreed that the structure of the anchor/header tags in the documentation
files is copied into the index.  This would maintain a lot of flexibility
for the authors, they only would have to maintain anchor tags for each
element they want in the index.

Christoph

-- 
POV-Ray tutorials, IsoWood include,                 
TransSkin and more: http://www.tu-bs.de/~y0013390/  
Last updated 14 Apr. 2002 _____./\/^>_*_<^\/\.______

Post a reply to this message

in news:3CBAF2B1.F2AD79E2@gmx.de Christoph Hormann wrote:

> - whether patch authors think this is feasible and useful

As a user of patches, to me it would be usefull to have a consistent 
layout of documentation for the various patches.

> - if other methods would be better

The ideal would be if every patcher used docbook and has the tools 
needed for processing it. But simple HTML will do fine, maybe with an 
extra tag or two for indexing keywords.

> - if such a system is created how it should be established (maybe
> something like official patch documentation guidelines?)
> 

HTML template (the povdoc could be the role model here), a guideline and 
some scripts or tools to process the files.

Speaking of tools, here is an interesting one. It takes a set of HTML 
files as input and returns one HTML file as output with an index based 
on the H-tags (tried it with the povdoc and works fine). You can also 
generate PDF and PS with it. Available for several platforms.

http://www.easysw.com/htmldoc/


Ingo

Post a reply to this message

ingo wrote:
> 
> The ideal would be if every patcher used docbook and has the tools
> needed for processing it. But simple HTML will do fine, maybe with an
> extra tag or two for indexing keywords.
> 
> [...]
> 
> HTML template (the povdoc could be the role model here), a guideline and
> some scripts or tools to process the files.
> 

That would be more than i suggested, it would involve processing all the
files to create the final documents.  Having a separate 'source version'
of the texts would also mean that if i want to 'recompile' it i have to
get the source first. I'm not sure if a keyword index would be really
necessary.

> Speaking of tools, here is an interesting one. It takes a set of HTML
> files as input and returns one HTML file as output with an index based
> on the H-tags (tried it with the povdoc and works fine). You can also
> generate PDF and PS with it. Available for several platforms.
> 
> http://www.easysw.com/htmldoc/

The toc.html file it generates is about what i considered, it just does
not work well when the different files do not all use the same level
structure, but this should not be a problem when the guidelines are
obeyed.  


Christoph

-- 
POV-Ray tutorials, IsoWood include,                 
TransSkin and more: http://www.tu-bs.de/~y0013390/  
Last updated 14 Apr. 2002 _____./\/^>_*_<^\/\.______

Post a reply to this message

"Tony[B]" wrote:
> 
> I think that such a system would be a great idea. Have you given any thought
> as to how you would implement it? www.wxwindows.org has something (wxHTML),
> which might help get things started.

This seems to be a pure Linux/Windows system so it won't be very useful
probably.

Christoph

-- 
POV-Ray tutorials, IsoWood include,                 
TransSkin and more: http://www.tu-bs.de/~y0013390/  
Last updated 14 Apr. 2002 _____./\/^>_*_<^\/\.______

Post a reply to this message

> This seems to be a pure Linux/Windows system so it won't be very useful
> probably.

I understand that they're working on a Mac port, and maybe just the wxHTML
part is usable alone. But, I'm not sure.

Post a reply to this message