Board index » delphi » Documentation Format to Source Control

Documentation Format to Source Control


2005-07-27 01:50:14 AM
delphi220
I'm looking for a non-binary format to keep tech documentation (like
specs) stored in my Subversion repository.
Plain text is not good because I need to create tables, format fonts
and things like that.
I tried RTF but when I alter a single line, it changes almost the
entire file. HTML is hard to mantain because off all the code WYSIWYG
editors put in it.
Maybe I am looking for a format that doesn't exist yet. :)
--
Erick Sasse
 
 

Re:Documentation Format to Source Control

On 26 Jul 2005 10:50:14 -0700, "Erick Sasse"
<XXXX@XXXXX.COM>writes:
Quote
I'm looking for a non-binary format to keep tech documentation (like
specs) stored in my Subversion repository.
OpenOffice 2 uses XML...
HTH
ain
 

Re:Documentation Format to Source Control

Ain Valtin writes:
Quote
OpenOffice 2 uses XML...
The OASIS OpenDocument format, but I think it is packed inside a zip
file, otherwise files would be very big.
--
Erick Sasse
 

Re:Documentation Format to Source Control

In article <42e677d6$XXXX@XXXXX.COM>, Erick Sasse wrote...
Quote
I tried RTF but when I alter a single line, it changes almost the
entire file. HTML is hard to mantain because off all the code WYSIWYG
editors put in it.
I use latex, but if you even don't want write HTML by hand, you probably
don't want{*word*178}either.
--
stefan
 

Re:Documentation Format to Source Control

Stefan Ascher writes:
Quote
I use latex, but if you even don't want write HTML by hand, you
probably don't want{*word*178}either.
I'll look at it. Thanks!
--
Erick Sasse
 

Re:Documentation Format to Source Control

In article <XXXX@XXXXX.COM>, Erick Sasse wrote...
Quote
I'll look at it. Thanks!
What I missed to say is that is is source code orientated. Even though
you can read the source -- it is plain text with formatting commands --
it's useful to compile it to PDF, PostScript or translate it to HTML.
However, I use it for almost all Text I write.
--
stefan
 

Re:Documentation Format to Source Control

In article <XXXX@XXXXX.COM>,
XXXX@XXXXX.COM says...
Quote
Stefan Ascher writes:

>I use latex, but if you even don't want write HTML by hand, you
>probably don't want{*word*178}either.

I'll look at it. Thanks!

I use the MiTeX implimention, which is free and WinEdt as my{*word*178}IDE
(if you will)
WinEdt can be found here:
www.winedt.com/
(it's summat like 30 bucks)
--
John
Life is complex. It has real and imaginary parts
 

Re:Documentation Format to Source Control

"Erick Sasse" <XXXX@XXXXX.COM>writes
Quote
Stefan Ascher writes:

>I use latex, but if you even don't want write HTML by hand, you
>probably don't want{*word*178}either.

I'll look at it. Thanks!

--
Erick Sasse
If{*word*178}is an option then you may want to check out Lyx, which is kind of a
graphical wrapper around{*word*178}that makes it easier to use.
www.lyx.org
-- Herbert Sitz
 

Re:Documentation Format to Source Control

"Erick Sasse" <XXXX@XXXXX.COM>writes
Quote
I'm looking for a non-binary format to keep tech documentation (like
specs) stored in my Subversion repository.

Plain text is not good because I need to create tables, format fonts
and things like that.

I tried RTF but when I alter a single line, it changes almost the
entire file. HTML is hard to mantain because off all the code WYSIWYG
editors put in it.

Maybe I am looking for a format that doesn't exist yet. :)

--
Erick Sasse
The diff viewing is not really part of subversion, it is just part of
whatever utility is used to load the subversion files. So for rtf files you
may want to try and see whether something like Beyond Compare will work:
www.scootersoftware.com/home.php
Also, you do know that MS Word has a fairly decent diff function of its own
that works on binary .doc files. I assume there's a way to jerry rig things
up so that the files you load out of subversion get diffed in word. Would
certainly be possible to do it manually, in any case (i.e., manually get
files out of subversion, then load into Word and view in its document
compare mode).
-- Herbert Sitz
 

Re:Documentation Format to Source Control

Hi,
Erick Sasse writes:
Quote
I'm looking for a non-binary format to keep tech documentation (like
specs) stored in my Subversion repository.

Plain text is not good because I need to create tables, format fonts
and things like that.

I tried RTF but when I alter a single line, it changes almost the
entire file. HTML is hard to mantain because off all the code WYSIWYG
editors put in it.
Have you looked into DocBook format?
It's XML based and I find it OK to even write with a simple editor because
it allows me to concentrate on content, not form. DocBook can be converted
into several different output formats, including HTML, PDF and latex.
Unfortunately installing the tool chain for actually creating any output
isn't trivial (or at least wasn't last time I looked into it, which was a
few years ago). I liked the concept very much back then, but unfortunately
was forced by management to use Microsoft Word instead. They paid for it
big time, because it took me much longer to finish the documentation with
MS Word than it would have with DocBook. And then I had to convert it to
HTML as source for the online help which took me another few days because
of the cr^H^Hless than perfect HTML export from MS Word.
twm
 

Re:Documentation Format to Source Control

Quote
Also, you do know that MS Word has a fairly decent diff function of
its own that works on binary .doc files. I assume there's a way to
jerry rig things up so that the files you load out of subversion get
diffed in word. Would certainly be possible to do it manually, in
any case (i.e., manually get files out of subversion, then load into
Word and view in its document compare mode).
Thanks, I will look at all recommendations.
--
Erick Sasse
 

Re:Documentation Format to Source Control

GenHelp and GenHelpPro use a text based format to store source code
documentation
in. I store everyting in CVS and don't have a problem. As it uses RTF for
the
formatting the output is good also.
GenHelp will create WinHelp or HTML output for web sites etc.
GenHelpPro uses template files to create any format you want. At present
it can create WinHelp, HtmlHelp, HtmlHelp 2, RTF for manuals which
can then be opened in OpenOffice to create PDF files.
And you can create your own templates or customise existing ones.
All formats are created from one source file.
See www.genhelp.co.uk for further details.
Cheers, Pete
GenHelp: "Source documentation made fun"
"Erick Sasse" <XXXX@XXXXX.COM>writes
Quote
>Also, you do know that MS Word has a fairly decent diff function of
>its own that works on binary .doc files. I assume there's a way to
>jerry rig things up so that the files you load out of subversion get
>diffed in word. Would certainly be possible to do it manually, in
>any case (i.e., manually get files out of subversion, then load into
>Word and view in its document compare mode).
 

Re:Documentation Format to Source Control

"Erick Sasse" <XXXX@XXXXX.COM>writes
Quote
>Also, you do know that MS Word has a fairly decent diff function of
>its own that works on binary .doc files. I assume there's a way to
>jerry rig things up so that the files you load out of subversion get
>diffed in word. Would certainly be possible to do it manually, in
>any case (i.e., manually get files out of subversion, then load into
>Word and view in its document compare mode).

Thanks, I will look at all recommendations.

If using MS Word's internal compare functionality is a possible alternative,
you can check it out by choose on the menu "Tools", "Track Changes",
"Compare documents". At least that is menu choice to access it in Word 2000.
Here's one of many web pages that outlines how to use it:
www.addbalance.com/usersguide/track_changes.htm
-- Herb