Documentation

[Colin Finck]

Hello,

Recently, some developers wrote documentation about certain stuff related to
ReactOS.
But this documentation was only placed on their own web servers.

In my opinion, it would be better if such stuff would (also) be committed to
the "documentation" directory in SVN.
Having documentation there makes sure that it does not get lost.
Additionally, if the source file is committed (not a PDF or something like
that), another person could extend the documentation further.
I agree that not all documentary stuff needs to be on SVN. An example might
be Magnus' Win32k syscall tables.
But for example Andrew Greenwood's documentation about the Windows
Multimedia Subsystems looks like something, which should be committed in my
opinion.

If you don't agree on committing this stuff, it would be nice if we could at
least agree on an official document format, which should be used in the SVN
tree.
>  From what I see, most documentations were created by
> using OpenOffice, so I 
think the OpenDocument Text format (ODT) would be a great
choice. It is also
supported by most word processors, thus most people should be able to open
an ODT file.
Up to now, I used RTF for formatted text documentations in SVN, but this
format does not support things like shapes.

Regards,

Colin

[Klemens Friedl]

My thoughts...

Plain Text
It cannon be denied that plain text is the single one format that
everyone can process on every system. A second format that is used
almost everywhere is the HTML syntax. Every platform has its
web-browser clients, be it text or graphical ones.

HTML
Additionally the HTML syntax is really simple, you don't have to use
extensive tags, some basic tags for bold, italic, underline, indent,
paragraph, line-break and how to create a simple table are enough. No
one has to use a simple text editor to write html documents, there are
a lot of WYSIWYG-Editors around (just don't use MS Word for that task,
or at least clean up afterwards).
In my opinion, it would be a good idea to use real standard formats
that are already in use for years and will be around in years too.

PDF
If you really want to use a read-only format, use PDF (version 1.4) or
PDF/A (archive).
Text documents should be saved in UTF-8, UTF-16 (or ANSI) and don't
forget to set the "svn:eol-style=native" svn tag.

SPREADSHEETS
For special cases like spreadsheets, CSV format or HTML tables would
be suitable too.

PRESENTATIONS
Presentations can be exported as PDF files or optionally as HTML
file(s). Nevertheless, PowerPoint presentation files are quit common
too.

PICTURES
Given the popular image formats, I would like to propose JPEG, PNG,
TIFF (and BMP) for bitmap graphics and maybe SVG, EPS (and AI) for
vector graphics.

OFFICE FORMATS
Regarding popular but (non-)standard and vendor specific office
formats, avoid them in svn repo, if possible. In general try to save
it as MS Office 97 documents. Almost every office software package can
at least import and read word 97 documents, additionally several (3,
one still active) open source projects exist that allow you to process
MS Office 97 files.

NEW OFFICE FORMATS
XML based office formats like the one form AbiWord,
OpenOffice/StarOffice, MS Office have one in common, all use the zip
format as container for its xml based documents.
While it can be opened and accessed more easily, currently only
limited range of tools exist that are able to parse them. Furthermore,
from current point of view we can only guess if most of these formats
will be still around and readable in the next few years. And don't
forget, to a certain degree it's already valid for MS Office 1-6, MS
Works, Lotus, etc. formats.


Klemens

[Colin Finck]

>   Klemens Friedl wrote:
>
>  Plain Text
>  It cannon be denied that plain text is the single one format that
>  everyone can process on every system. 
Agreed. If it's really just *simple* text, the plain text format should be
used.


>   HTML
>  Additionally the HTML syntax is really simple, you don't have to use
>  extensive tags, some basic tags for bold, italic, underline, indent,
>  paragraph, line-break and how to create a simple table are enough. 
HTML might also be suitable for certain cases.
But in a HTML file, you cannot embed any other files like images. All the
Office formats can embed these files and they are also more suitable if a
documentation shall be printed.


>   PDF
>  If you really want to use a read-only format, use PDF (version 1.4) or
>  PDF/A (archive). 
Agreed, but in general I think that read-only formats should be avoided for
documentations.
Otherwise it's quite hard to extend this documentation further.


>   Text documents should be saved in UTF-8, UTF-16 (or
> ANSI) and don't
>  forget to set the "svn:eol-style=native" svn tag. 
I would only save them in ANSI, then it's sure that everyone can read them.
Some Unix-based operating systems might still have problems with Unicode.
Unicode formats should only be used if these characters are really needed
and as most documentation will be in english, I doubt that Unicode is needed
often.


>   In general try to save it as MS Office 97 documents.
> Almost every office 
software package can
>   at least import and read word 97 documents 
But there is no open specification about the Office 97 document formats.
And as many developers already seem to use OpenOffice or another Office
suite, which is able to read OpenDocument files, I would recommend using
these formats.
Also the OpenDocument format was accepted as an ISO standard, so I highly
doubt that it won't be readable in some years.


>   And don't forget, to a certain degree it's
> already valid for MS Office 
1-6, MS
>   Works, Lotus, etc. formats. 
MS Office 1-6 formats should still be readable by today's applications,
which also support the Office 97 formats.
The other proprietary file formats were only supported by a very few number
of applications and their specifications are not openly available, so it's
no surprise that they are dead now.

Regards,

Colin

[Marc Piulachs]

Hi All,

A part from the documentation generated by the developers I think we should
start thinking about the End-User documentation.

Having complete and localized end user documentation (winhelp/htmlhelp) for
every application will take years so never is too early to start and a lot
of non developer community members can contribute.

My proposal is to place the documentation in a standardized folder in every
module in the source tree for example "docs" or "help"

The most obvious choice for me is to use docbook (see
http://www.codeproject.com/winhelp/docbook_howto.asp for an introduction to
docbook) 

The idea is to use a different file for every language, for example:

\base\applications\calc\help\en-US.xml
\base\applications\calc\help\es-Es.xml
....

Then we can add a new tag to rbuild to generate the end-user documentation
in any format we desire (man , winhelp , htmlhelp or plain html to publish
on the web) as part of the standard build. Something like that:

<directory name="help">
	<helpfile locale="en-US">en-US.xml</helpfile>
	<helpfile locale="es-ES">es-ES.xml</helpfile>
</directory>

It seems a simple solution to implement.

Marc,

-----Original Message-----
From: ros-dev-bounces(a)reactos.org [mailto:[e-mail]] On
Behalf Of Colin Finck
Sent: Wednesday, September 19, 2007 7:34 PM
To: ros-dev(a)reactos.org
Subject: [ros-dev] Documentation

Hello,

Recently, some developers wrote documentation about certain stuff related to
ReactOS.
But this documentation was only placed on their own web servers.

In my opinion, it would be better if such stuff would (also) be committed to
the "documentation" directory in SVN.
Having documentation there makes sure that it does not get lost.
Additionally, if the source file is committed (not a PDF or something like
that), another person could extend the documentation further.
I agree that not all documentary stuff needs to be on SVN. An example might
be Magnus' Win32k syscall tables.
But for example Andrew Greenwood's documentation about the Windows
Multimedia Subsystems looks like something, which should be committed in my
opinion.

If you don't agree on committing this stuff, it would be nice if we could at
least agree on an official document format, which should be used in the SVN
tree.
>  From what I see, most documentations were created by
> using OpenOffice, so I 
think the OpenDocument Text format (ODT) would be a great
choice. It is also
supported by most word processors, thus most people should be able to open
an ODT file.
Up to now, I used RTF for formatted text documentations in SVN, but this
format does not support things like shapes.

Regards,

Colin

_______________________________________________
Ros-dev mailing list
Ros-dev(a)reactos.org
http://www.reactos.org/mailman/listinfo/ros-dev

[Magnus Olsen]

Hi
My document I share some times on irc is my private document, it only be
share time to time
the syscall table was done for only one pruprles to  make our own win32k
more compatble
and see smaller diffent also part of a book I trying to write. it can end up
be public doc in svn
in futuer I do not yet. this material I doing is basic for a book I trying
to write. and I share some
part from it to public, and some part u for pay for, ofcures it is free for
other ros devs that need
that info.

----- Original Message ----- 
From: "Colin Finck" <mail(a)colinfinck.de>
To: <ros-dev(a)reactos.org>
Sent: Wednesday, September 19, 2007 7:33 PM
Subject: [ros-dev] Documentation


>   Hello,
>
>  Recently, some developers wrote documentation about certain stuff related 
to
>   ReactOS.
>  But this documentation was only placed on their own web servers.
>
>  In my opinion, it would be better if such stuff would (also) be committed 
to
>   the "documentation" directory in SVN.
>  Having documentation there makes sure that it does not get lost.
>  Additionally, if the source file is committed (not a PDF or something like
>  that), another person could extend the documentation further.
>  I agree that not all documentary stuff needs to be on SVN. An example 
might
>   be Magnus' Win32k syscall tables.
>  But for example Andrew Greenwood's documentation about the Windows
>  Multimedia Subsystems looks like something, which should be committed in 
my
>   opinion.
>
>  If you don't agree on committing this stuff, it would be nice if we could 
at
>   least agree on an official document format, which
> should be used in the 
SVN
>   tree.
>  >From what I see, most documentations were created by using OpenOffice, so 
I
>   think the OpenDocument Text format (ODT) would be a
> great choice. It is 
also
>   supported by most word processors, thus most people
> should be able to open
>  an ODT file.
>  Up to now, I used RTF for formatted text documentations in SVN, but this
>  format does not support things like shapes.
>
>  Regards,
>
>  Colin
>
>  _______________________________________________
>  Ros-dev mailing list
>  Ros-dev(a)reactos.org
>  http://www.reactos.org/mailman/listinfo/ros-dev

[Timo Kreuzer]

My thoughts about documentation:

1. Documenting windows functionality and technical stuff
Andrew Greenwood's documentation is wiki based. And I think that isn't a 
bad idea. (I already thought about creating a small wiki like that 
myself) It provides all means of formatting needed, can be viewed by 
everyone using a webbrowser, you can add links, non-devs could add their 
own findings and we already have a wiki in place. Maybe we should add a 
tech-wiki or something where this stuff could go.
It wouldn't be in our source tree, but I don't think that is really 
needed. IMHO it's way better than a bunch of different format text files.

2. Source code documentation
We currently have a very outdated version of doxygen (both doxygen 
itself and the processed source are really outdated). I currently use 
either koders or krugle to search our code. But both also use quite 
outdated sources (around 0.3.0). So we should think about updating our 
doxygen and probably keeping it at a quite up to date state (only a few 
days old if possible).
Some time ago I had begun to create my own documentation system, but it 
turns out it would be a huge bunch of work to get all the features in 
that doxygen already provides. I only think that doxygen output doesn't 
look that good. So I thought about creating a program that could parse 
doxygen's XML output and create something more MSDN alike.
We should also start to think about a consistent way to write code 
documentation. It's done in several different ways. Ok, we need to stick 
to wine documentation for their code. But we should have a consistent 
style for our own code, like always using @param, @return, etc.

3. Program documentation
Docbook depends on cygwin and for chm's also on ms html help workshop. 
To automatically build the chm's we would need a win32/mingw port of the 
needed tools (sed, xsltproc,...) and we would need an open source chm 
compiler. There's an SoC project from wine: 
http://wiki.winehq.org/SummerOfCode, looks like it was just finished: 
http://www.nabble.com/-1-3--whhc---add-chm-compiler-t4361318.html
We could also simply stick to .hhp / .html files.

Timo

[Ged]

Timo Kreuzer wrote:
>   So we should think about updating our 
>  doxygen and probably keeping it at a quite up to date state (only a few 
>  days old if possible). 
I fully agree.
Aleksey, is there any reason this can't be stuck in a cron job and run
weekly?
Doxygen is a great tool which we can't really make much use of at the
moment.

Ged.






This message contains confidential information and is intended only for the individual
named. If you are not the named addressee you should not disseminate, distribute or copy
this e-mail. Please notify the sender immediately by e-mail if you have received this
e-mail by mistake and delete this e-mail from your system. E-mail transmission cannot be
guaranteed to be secure or error-free as information could be intercepted, corrupted,
lost, destroyed, arrive late or incomplete, or contain viruses. The sender therefore does
not accept liability for any errors or omissions in the contents of this message, which
arise as a result of e-mail transmission. If verification is required please request a
hard-copy version. 

Amteus Secure Communications Ltd
57 Cardigan Lane,
Leeds, 
LS4 2LE
t: [phone]
f: [phone]

Registered in England No 4760795

http://www.amteus.com

[Colin Finck]

Timo Kreuzer wrote:

>   1. Documenting windows functionality and technical
> stuff
>  Andrew Greenwood's documentation is wiki based. 
In fact, I was referring to this PDF he published:
http://stuff.silverblade.co.uk/reactos/windows_mm.pdf
But I also saw his Wiki documentation and yes, this can't just be committed
to SVN.


>   Maybe we should add a 
>  tech-wiki or something where this stuff could go. 
In my opinion, this is a great idea. But this technical Wiki should really
be separated from our current Wiki.
The easiest way to do this would be using pseudo directories like we already
do for separating the languages. ("De/", "Fr/", ...)

But first I'd recommend doing a cleanup of the existing Wiki.
There are still many outdated pages there and the main page is quite
unclear. In my opinion, a main page layout like at
http://www.linuxbios.org/index.php/Welcome_to_LinuxBIOS would be easier and
clearer. Now that we have image uploads enabled, adding graphics to the main
page is also feasable.
What do you think about this idea?


>   2. Source code documentation
>  So we should think about  updating our doxygen [...]
>  I only think that doxygen output doesn't look that good. 
I agree on both.
As we already had Doxygen working and it seems to have many features, I
think we should use it.
Although, its output does not look that good in the current state, it can be
customized. For example, just look how the Doxygen-generated documentation
looks at the KDE Website: http://developer.kde.org/documentation/library/


>   3. Program documentation 
For program documentation, I would go for using CHM files. They are easy to
use, the help layout is consistent and viewing CHM files is a part that we
have to implement anyway somewhen.
But this also requires setting up a system for creating the documentation
files. If we need to reimplement DocBook and friends for Win32, this would
most-probably result in a huge amount of work, for which no one has time for
:-(

Regards,

Colin

[Timo Kreuzer]

Colin Finck schrieb:
> >   Maybe we
> > should add a 
> >  tech-wiki or something where this stuff could go.
> >       
>  In my opinion, this is a great idea. But this technical Wiki should really
>  be separated from our current Wiki.
>  The easiest way to do this would be using pseudo directories like we already
>  do for separating the languages. ("De/", "Fr/", ...)
>     
I would vote for a real seperation. It might be a little work to set it 
up, but I think it's worth it. If we simply used "/tech" or something it 
would result in our wiki being even more messed up ;-) And searching 
would always be done in both the normal wiki and the tech-wiki, which I 
think is not so good.

>   But first I'd recommend doing a cleanup of the
> existing Wiki.
>     
I agree, it could need some love. Now that we have a bugzilla 
maintainer, what about a website content maintainer?

>   For program documentation, I would go for using CHM
> files. They are easy to
>  use, the help layout is consistent and viewing CHM files is a part that we
>  have to implement anyway somewhen.
>  But this also requires setting up a system for creating the documentation
>  files. If we need to reimplement DocBook and friends for Win32, this would
>  most-probably result in a huge amount of work, for which no one has time for
>  :-(
>     
We could import hhm from wine. But afaik it only creates the archive, 
not the internal files. So we would need to write a program that 
generates the internal files from the hhp, hhc and hhk files. They are 
well documented. Or we wait until wine has finished that stuff.

Timo

[Steven Edwards]

On 9/20/07, Timo Kreuzer <timo.kreuzer(a)web.de> wrote:
>    We could import hhm from wine. But afaik it only
> creates the archive, not
>  the internal files. So we would need to write a program that generates the
>  internal files from the hhp, hhc and hhk files. They are well documented. Or
>  we wait until wine has finished that stuff. 
There was a win32 chm compiler and example help file submitted to
wine-patches a while back. Feel free to import that and the htmlhelp
dlls and viewer. Your going to need it anyway to be compatible with
Windows documentation. Its pseudo-html source so exporting to
PDF/ODF/DOCX/etc should not be too hard.

-- 
Steven Edwards

"There is one thing stronger than all the armies in the world, and
that is an idea whose time has come." - Victor Hugo

[Steven Edwards]

On 9/21/07, Steven Edwards <winehacker(a)gmail.com> wrote:
>   There was a win32 chm compiler and example help file
> submitted to
>  wine-patches a while back. Feel free to import that and the htmlhelp
>  dlls and viewer. Your going to need it anyway to be compatible with
>  Windows documentation. Its pseudo-html source so exporting to
>  PDF/ODF/DOCX/etc should not be too hard. 
Oh and just to weigh in, not being an active developer, no one should
care what I say but.....ReactOS used docbook before and we hated it. I
used to also have to use docbook for my job and I hated it. Wine used
to use SGML for docs and we hated it. Wiki's are the way to go. Make
it easy for the non-programers to write a good chunk of the
documentation and translations. Save your developers time by not
requiring even more oddball tools with cryptic commands and syntax.
Use a wiki with an export feature and export it to a standard open
format that you can plug in to HTMLhelp later.

Did I mention I hate docbook?

-- 
Steven Edwards

"There is one thing stronger than all the armies in the world, and
that is an idea whose time has come." - Victor Hugo

[Klemens Friedl]

On 9/21/07, Steven Edwards <winehacker(a)gmail.com> wrote:
>   There was a win32 chm compiler and example help file
> submitted to
>  wine-patches a while back. Feel free to import that and the htmlhelp
>  dlls and viewer. Your going to need it anyway to be compatible with
>  Windows documentation. 
other chm tools:
http://www.jedrea.com/chmlib/
http://bonedaddy.net/pabs3/code/#hhm

In near future, we will need a chm and hlp viewer in ReactOS. A chm
viewer will require a HTML (render) engine, e.g. download gecko
activex control during first start of the app.

As an alternative, we could use PDF files for our own (currently not
existing) ReactOS help-system.
It would be less cumbersome to include (to our svn repo; e.g.
"rosapps") a lightweight pdf library plus a basic pdf viewer app (not
a Acrobat competitor, but similar to MacOS X pdf viewer, or KDE/Gnome
pdf viewer) in comparision to "beasts" like gecko (mozilla) or webkit
(apple).
(I have already investigated in this direction maybe there is interest
for such a solution.)


>   Did I mention I hate docbook?
>  Wine used to use SGML for docs and we hated it. 
Old docbook versions required the
complex SGML, newer versions use XML.
our unmaintained docbook svn dir:
http://svn.reactos.org/svn/reactos/trunk/rosdocs/

>   [...] ReactOS used docbook before and we hated it. I
>  used to also have to use docbook for my job and I hated it. 
In retrospect a funny snip from our rosdoc's readme.txt:
"This document should be written in RosDocs, to demonstrate its power. But
since RosDocs is, let's be frank, vaporware, and since I'm still looking for an
XML editor that 1) doesn't suck and 2) isn't written in Java (but this is a bit
redundant), *and* since I was supposed to finish this document some two weeks
ago, hand-formatted plaintext wins, for the moment."
-- by our beloved dev and ex-librarian KJK::Hyperion ;)


>   Wiki's are the way to go. 
Mozilla uses
MediaWiki too, similar to our setup with language interlink.
http://developer.mozilla.org/en/docs/Main_Page
http://developer.mozilla.org/en/docs/About_JavaScript

>   Use a wiki with an export feature and export it to a
> standard open
>  format that you can plug in to HTMLhelp later. 
MediaWiki allows both basic HTML
syntax as well as the special Wiki
syntax; you can even mix them in one document.

MediaWiki extention - PDF export:
http://www.mediawiki.org/wiki/Extension:Pdf_Export


Klemens

[Ged]

Klemens Friedl wrote:

>   In near future, we will need a chm and hlp viewer in
> ReactOS 
We already have one, it's just not fully working yet.
A while ago I imported hhctrl.ocx from Wine and I wrote a quick hh.exe to
call into this.

Ged.







This message contains confidential information and is intended only for the individual
named. If you are not the named addressee you should not disseminate, distribute or copy
this e-mail. Please notify the sender immediately by e-mail if you have received this
e-mail by mistake and delete this e-mail from your system. E-mail transmission cannot be
guaranteed to be secure or error-free as information could be intercepted, corrupted,
lost, destroyed, arrive late or incomplete, or contain viruses. The sender therefore does
not accept liability for any errors or omissions in the contents of this message, which
arise as a result of e-mail transmission. If verification is required please request a
hard-copy version. 

Amteus Secure Communications Ltd
57 Cardigan Lane,
Leeds, 
LS4 2LE
t: [phone]
f: [phone]

Registered in England No 4760795

http://www.amteus.com

[Timo Kreuzer]

Klemens Friedl schrieb:
>  
> >   Use a wiki with an export feature and export it
> > to a standard open
> >  format that you can plug in to HTMLhelp later.
> >       
>  MediaWiki allows both basic HTML syntax as well as the special Wiki
>  syntax; you can even mix them in one document.
>
>  MediaWiki extention - PDF export:
>  http://www.mediawiki.org/wiki/Extension:Pdf_Export
>     
What about MediaWiki publisher? http://mwpublisher.org/Main_Page
We would still need a chm compiler, but writing the documentation could 
be done using our wiki.
The previews look very good.

Timo

[Klemens Friedl]

2007/9/21, Timo Kreuzer <timo.kreuzer(a)web.de>de>:
>   What about MediaWiki publisher?
>  http://mwpublisher.org/Main_Page
>  We would still need a chm compiler, but writing the documentation could be
>  done using our wiki. 
It replies on a shareware app called helpblocks
(http://www.helpblocks.com).
So not an option for us.



Exporting html pages out of MediaWiki is not the problem.
We just need a chm compiler (see links in previous mails) and a few
lines of (script) code to process it in an automatic way.
In the same way we could optionally also provide pdf files of the same content.

[Steven Edwards]

On 9/21/07, Klemens Friedl <frik85(a)gmail.com> wrote:
>   In near future, we will need a chm and hlp viewer in
> ReactOS. A chm
>  viewer will require a HTML (render) engine, e.g. download gecko
>  activex control during first start of the app. 
Wine now implements almost all of this.

-- 
Steven Edwards

"There is one thing stronger than all the armies in the world, and
that is an idea whose time has come." - Victor Hugo

[Timo Kreuzer]

Steven Edwards schrieb:
>   There was a win32 chm compiler and example help file
> submitted to
>  wine-patches a while back. Feel free to import that and the htmlhelp
>  dlls and viewer. Your going to need it anyway to be compatible with
>  Windows documentation. Its pseudo-html source so exporting to
>  PDF/ODF/DOCX/etc should not be too hard.
>     
The hhm project page (http://savannah.nongnu.org/projects/hhm) says 
"Currently it can create the archive format, but no internal files."
Does the one in wine compile a full .chm with all internal files from a 
.hhp etc file?