Slashdot Mirror
Writing Documentation
"So far, I like aft,
mostly because it is simple to use, and gives me nice result as HTML.
Unfortunately HTML is not enough, since I also need a very good looking
printable version.
There are alternatives like DocBook,
which I could not get to work and udo
(Page is German, get the translation from the fish) which I have not yet looked
into very closely.
Then of course there is TeX and any number of WYSIWY-won't-G word
processors. I haven't used TeX much, I only tried my luck in writing
a few letters (and found out that it is not suitable for this). I went
through hell when I wrote larger documents with various versions of
MS Word and I am not really a fan of Star Office even though version
5.2 has not yet crashed on me (however 6.0 beta did). KWord, part of
KOffice doesn't seem to be stable enough yet.
I would prefer a simple ASCII only format as the source for being
converted to more complex formats anyway, especially since it could
be easily put into CVS for version management (Anybody tried that
with MS-Word documents? Don't!)
As all these projects show I am not the first one faced with this
problem. I wonder what experiences Slashdot readers have had with
these and other packages?"
Not to disparage any other product, open source or not, but if Word is crashing on you regularily, you are doing something wrong.
I've use all versions of Word from v2.0 to 2000 (no XP) and while I have had crashes, they are rare. I have written over a hundred articles, averaging 1300 words and a book using Word and have lost very little.
Just out of curiousity, what are you writing documentation for? I myself would approach the problem according to what kind of software it was, and who the intended audience was.
It will do versioning. See the menu file/versions
the choice is obvious padawan.... vi. may the source be with you.
the samba guys used to use YODL before they switched to docbook. pretty easy to use, and you can convert to other document languages including html, latex, etc.
http://www.xs4all.nl/~jantien/yodl/
Have you tried LyX? It's a very powerful multiplatform typesetting program. Seems to do everything you want it to do.
Marxism is the opiate of dumbasses
If it was hard to write it should be hard to understand.
Doxygen lets you mark up your source code pretty easily, and generates decent looking documents. You can use the same markup (and cross-reference facilities) in non-code documents processed at the same time.
I've used Doxygen with good results. It has various output formats (HTML, RTF, man, etc.).
http://www.stack.nl/~dimitri/doxygen/
full disclosure: I hate documentation (unless its in other people's code ;) and I've been able to luck out in working at places where we need the code written so fast that documentation is an afterthought.
....
what about javadoc (is it still called that)? it's good for turning well-formatted function summaries into browsable HTML
Are we talking API documentation here, or real-world english implementation documentation? if you're looking for just a good ASCII editor, straight off, ultraedit is easily my favorite, but if you are looking for stuff to skim your source and rip out inline documentation, obviously, thats not what you're looking for. but javadoc might be?
"Old man yells at systemd"
I have the same "problem" and I use XML for the document source. Using XSL (xalan/xerces or any other xsl/xml library) I transform it into HTML, PDF, ...
A perfekt solution!
-B
Ash and Hickory, straight-grained and true, make excellent bludgeons, dandy for the cudgeling of vegetarians.
- Do feature reqs (10%)
- Do design spec / unit spec (30%)
- Do documentation (30%)
- Write code (15%)
- Beta-test / debug (15%)
Notice that design and documentation take up more than half the time on the project. Implementing the code becomes very easy with good, fleshed-out design and documentation.As for solving your problem, I generally write documentation in-code using one style of comments and line-by-line comments using another style. Then forming docs from the code is easy: write a little perl script to extract the block comments, and format as you like.
This post expresses my opinion, not that of my employer. And yes, IAAL.
couple with a few other tools you can easily generate html, rtf, info, man and pdf files.
I'm sure TeX or LaTeX with a few custom macros could simplify the process a bit, as well as provide multiple output formats.
Personally, I use LaTeX for everything now; there's tons of packages available for whatever you might happen need to do.
I use docbook. Once you get a handle on it and make some staring templates, it is the way to go.
SGML was designed for tech docs.
LaTex isn't very difficult once you know a few basic commands, outputs to text, dvi, and pdf, and basically meets all the criteria for which you are looking - namely it does everything in ascii text. Think about Tex like emacs or vi - it's a great tool once you get used to it. It IS your solution.
Call me a throwback or GNU-head but I like texinfo. The stuff you type reflects the structure of your document, it's plain ascii (easy to edit with emacs or your favorite editor), and compiles to online docs, html, or printed docs using TeX. It does make some impositions on your writing style but I find the texinfo formatting commands much easier to deal with than (say) html tags. I use it even when I want plain ascii docs. I just don't put in any "node" commands. Then I run the texinfo doc
through the emacs formatter and use the formatted ascii output.
So, it's old and limited but still my favorite.
Or better yet, crash the plane into Mecca!
It depends on your specific needs. Are you documenting the source or documenting program usage? For the former, doxygen may be useful to you. Generates HTML and LaTeX, amongs other formats.
dan.
I have been charged with writing lots of documents, some smaller some larger, most of them documenting programs I wrote myself.
That sounds suspicious to me. When all of your code is documented, you'll become expandable. Some might even say that writing documentation is like writing your own layoff proposal. Watch your back.
Find something similar to Javadoc (unless you code in Java). Rational has a great set of suites to also document projects.
And I don't think "documenting" is the worst part of programming. Its very sterotypical.
I love design, and document while coding (usually in Java with Javadoc comments). Isn't that the way you are supposed to code?
Especially in a team environment (even more "especially" with Open Source), documentation is critical. Having a good design documented well is how developers should interact with one another.
Also check TogetherSoft. They have software that creates the UML while you code.
I also like Together's identification of titles. A "Developer" is someone that designs, codes, and documents. A "Coder" is someone that codes. Which are you?
Good quote, too many chars. Seriously, the slashdot 120 char limit sucks!
I'm doing a bunch of documentation right now, and I *LOVE* docbook. I agree, it's a bit of a pain to set up; we started with openjade as a basis, and worked from there.
:)
Still, I love the format; it's clear, it's precise, and it's very well-suited to documentation.
BTW, I'd like to point out that, if you think documentation is the worst part of programming, you're probably not writing very good documentation. Documentation can be a lot of fun. Think of it as a way to make sure that you won't have to do the maintenance later, because anyone will be able to do it based on your writing.
My blog: http://www.seebs.net/log/ --- My iPhone/iPad app: http://www.seebs.net/seebsfrac/
Nope, not me, I must be someone else...
Writing documentation is a tiresome and, what's worse, an unglorious job. Rarely do people talk about how great the documentation was and how much it helped them in succeeding. Everybody loves the programmer who adds a feature. Nobody knows the writer who explained it. If we want better documentation, that has got to change. I know I was very eager to create even better documentation when I received compliments about it.
HTMLDOC appears to serve your purpouse. It appears only windows binaries are avalible however but the sourcecode is avalible under the GPL
Where can I find documentation about
Microsoft Craporation software that doesnt
follow the following pattern:?
topic a: See topic b.
topic b: See topic a.
Thanks in advance,
Defeat Bush in '02.
We use it.
http://www.ehelp.com/products/robohelp/
This works nicely on very simple HTML (tables, images, font sizes and blockquotes), and is open source. I use it for purposes similar to those requested by the submitter. I write HTML in HotMetal (an easy to use Dreamweaverish thing on Windows) then run it through htmldoc on linux to get a PDF. As far as I can tell you have to settle for Times Roman, Helvetica and/or Courier in the text output. It handles jpegs and non-transparent gifs as well.
It seems to be abandonware, but it's a handy tool to have around.
----
mt
I've been writing documentation for a little while now and LaTeX always seemed the best way to solve the problem. You can make nice pdf and print version. Yes it takes some time to get use to and most WYSIWYG people don't like it but it rocks in CVS.
I believe there are other systems that implement a Javadoc like utility for other language. Do a google for "Javadoc for C++" for example and plent of links show up.
Try a Wiki.
A fairly simple web application that allows a group to work on documentation together. Since it uses simple formatting rules, it's trivial to learn.
It's the simplest way I know to let a workgroup develop a document.
They have Wiki's that run on Perl, Python, Smalltalk, and PHP so it's easy to find one that you can modify to your heart's content.
Most of the advanced wiki's have all types of bells and whistles (Eg: version control, authenicated users). Some of the wiki's can dump everything from the Wiki database to static HTML or TXT for further processing (which is nice when you actually want to publish).
My father is a blogger.
You don't understand sarcasm, do you?
What kind of a civilised nation drugs the suspects, makes them face military justice of a foreign civilisation and may even execute them (something the most, if not all, western nations frown upon!)?
I bet you'd agree to torture as well?
and more.
The main problem with Word is once you start reaching large manual size it starts faltering over the size of the doc as it likes to keep the whole thing in memory at once. If you are an advanced user then using the master / sub documents is a nice way around this - and follows all the object oriented principles of abstraction at the same time ;-)
Some of the best editors I have found for manual documentation tend to be code editors with folding capability - being able to fold a document on various heading types is invaluable!!
--*--*-- The Eagle sneers at the Peacock
In most of my projects, i write documentation into the code (think javadoc) and use the perl software for generating man pages from that. But that's only for documenting code.
If you're writing actual user documentation, i'd suggest using a flat text format with some delimeters in it, and then use perl to process that into HTML, TeX, or whatever intermediate format you'd like, and then process that into your PDFs using any of the available tools.
Pros: you control the entire process, so it comes out just how you want it. the filters you write can be stored in CVS right next to the documents they're run against, so you can track changes easily
Cons: you have to use Yet Another Language. you have to maintain things. you lose the "look and feel" of certain generators.
overall, i like the tradeoff, but i'm also notorious for being picky about things being Mine.
Basically, what we did is had all cvs check ins mirror to our postgresql database. There was a quickly hacked internal web site that would display the latest version of each document. In addtion, we had a link that run our script to make a pretty-print version as pdf or post-script output. I don't know of any easy to install package that does this, but setting this up didn't take much of our time. Good luck!
I have automated its use on several projects. Make a cron job that:
- Gets a copy of the latest sources from CVS
- Runs javadoc against the fresh sources
Each morning you'll have up-to-date documentation.-Andy
I'm using gobeProductive 3.0.2 on Windows (they have or will have a Linux version). It's like a light-weight replacement for MS Office, done by the same team that did Claris Works for the Mac.
The word processor is very easy to use, and can save in the gobeProductive format, as well as Word, HTML, PDF, RTF, and plain text.
The office suite also has spreadsheet, graphics, image processing, and presentation software.
http://www.gobe.com/
"And like that
When I wrote my thesis in College, I went through a similar process of trying to figure out what to use on a Linux platform. For the thesis, the choice was fairly clear: TeX and friends (I used LaTeX). It might seem a bit overkill to use for documentation, but I'd recommend giving it an extended try.
.tex|.bib files; they're raw text. You can take your tex files and convert to HTML and postscript with ease.
The Good: You can use CVS on your
The Bad: You're learning a new markup language.
The Ugly: My thesis, when converted to HTML, didn't look very good because all of the math equations got turned into gifs. However, things may have changed since then (1997) and since you're writing documentation, it may be a non-issue.
If Word crashes for you, I don't want you near any documentation projects, let alone actual code.
Jesus. Word crashing. Anyone who does that deserves a freakin' Darwin.
"The Native Americans must resolve their differences with Pakistan peacefully!"- George W. Bush
I would prefer a simple ASCII only format as the source for being converted to more complex formats anyway, especially since it could be easily put into CVS for version management (Anybody tried that with MS-Word documents? Don't!)
So what's the problem again? You can't put word documents in CVS or you don't recommend it? We have been using CVS to store documentation in binary format for a long time now, and we have never had a problem.
http://www.e-press.com
MS Word (Semi) Compatable, HTML and Adobe PDF Support
Download for free
_
Insert sig here (slashdot) Insert cig here (Lewinsky)
The benefit of using
LyX is that it can do both LaTeX and DocBook
output. That means it can basically export to any
useful format you might need (although MS-Word
.doc output might be a little awkward).
Don't discount DocBook just because it's a pig to
install and set up, it is a professional and pretty
well-designed documentation solution. Talk to the
LinuxDoc people if you don't believe me (who,
incidentally, are still considering making LyX the semi-official
application for editing their HOWTOs).
But then, I'm biased.
--
-- Remove the trailing '\0' to email me.
The best one I've used is Doxygen, by Dimitri van Heesh. This was developed for the KDE project. It is free too, which is hard to beat.
- Convert HTML files to PDF or PostScript
- Generate a table-of-contents for books
- Generate indexed HTML files
- Generate files on-the-fly for web applications, from the command- line for batch jobs, or from a GUI for interactive work.
It might not be the silver bullet but it can help you with making various formats for your docs.--
If I actually could spell I'd have spelled it right in the first place.
If one application is crashy then that means that, in all probability, that it's the applications fault. We're not talking about a 3d game where they might rely on a bunch of unstable libraries - MS Word sticks to the path and is quite beautiful and simple in it's interface with the OS. But it crashes more than other software, undoubtably.
The trick is to fill your documentation
with irony. Pity the poor user, and be
ironic about it. =)
A few notes from my experience:
HTML: easy to write, easy to format. HTML TIDY will make everything beautiful for you. HTML actually prints very nicely. I believe most browsers will let you turn off the default page header/footers. I can see, however, that page breaks might be an issue. You'll probably want to use style sheets anyway, and there's a feature in CSS2 that allows for defining page breaks (Paged Media documentation). Also see Converting HTML to other formats.
LaTeX: Personally, I'm a big fan of LaTeX. Never tried pure TeX. However, once (if!) I master the CSS2 paged media commands, I'll probably abandon LaTeX. I don't know that one's really any easier than the other; it's just comes down to the simple fact that I know HTML better.
LyX: I found this very non-intuitive and gave up on it quickly. As I recall, the tab key did not work as I expected it, and various things just weren't what I expected them to be.
Word: I know you, the poster, don't want to use Word, so this is for others who must use it. I dislike MS as much as the next /., but I must say that Word is actually a very good product. There are things that annoy me (especially placement of pictures), and there's the macro virus issue, but you probably don't need macros in documentation anyway. As someone else pointed out, there are versioning features in Word. In addition, there are collaboration features that let you track, accept, and reject changes. The style sheets are pretty powerful (most people never use them), and allow you to quickly and easily create tables of contents. And of course, if you're in Windows and have Word already, and assuming it does not constantly crash, it's really the easiest thing to use. Just don't try exporting your document to HTML!
hi.
I always use Notetab (or just any other editor). Anything else makes me work more with the layout than the contents.
/LosManos
I have been most impressed with extended plain TeX. It offers some niceties that plain TeX does not offer, but is not nearly as controlling and pigeon-holing as LaTeX. I don't know of any good, integrated tools out there for UNIX systems, other than maybe Emacs (what doesn't Emacs do?) but a few scripts go a long way. As far as documentation, The TeX-book is the bible, and a search on Google for tutorials provided me with a fair amount of good material. The learning curve? Well, I was able to produce some decent stuff after a day, much better stuff after a week, and it just got better after that.
However, keep in mind that TeX is limited. It only can only render text horizontally (no rotations) and it can't render graphics itself. Postscript is needed for that. Also, translation to HTML can be iffy with a lot of equations or symbols or things of that sort.
Remember WordPerfect? Version 9, SP4, is rock solid stable and does not suffer from Word's inability to handle long documents. (The primary culprit: Word's continuous repagination and reformatting, required by the document structure.) Versioning is supported, and WordPerfect, unlike Word, has the native ability to generate PDF files. Version 10, SP2 does even better, formatting hyperlinks automatically in PDF files, but I won't recommend it yet because there's a nasty interaction bug between it and Mozilla.
Not to mention WordPerfect's ultimate advantage over Word: Reveal Codes. In Word, any fouled-up formatting can only be fixed by *different* formatting. In WordPerfect, you can *remove* offending code. And it's more customizable, doing things the way you want them done, not the way Microsoft dictates. I could go on about dozens of other advantages, too.
Oh yeah, there are Linux versions available too (albeit using Wine).
Frankly, I'm amazed that any person with technical knowledge and expertise would use Word by choice.
TANSTAAFL
in particular these resources
And, so how are you able to run a diff of some sort against your document? Unless your tools supports this (MS Word does BTW), then you are SOL. I think it's too much to ask the version management software to do that.
Now, if you're using pure ASCII files to do your document, you can easily diff the file and inspect it using many other common stream tools (e.g. grep, perl, wc, uniq, etc.) for many purposes.
Please mod this post only if you think others should/n't read this. I have enough ego^H^H^Hkarma. Thanks!
We're using the preloaded docbook on RH7.2
and it works fine.
Grab some emacs elisp files from sourceforge
to round out the package and you are good to go
with tag completion and font color locking
in emacs.
Docbook advantages:
* no worries about formatting, just write content
* can generate html, postscript, possibly wml, carved stone tablets, etc.
* can be parsed by freely available xml parsers
to intelligently extract, say, all authors, all section titles. This could be done with raw
perl, but why rewrite an xml parser when so
many already exist?
* documents can be easily stored in an OODB,
using an xml->object marshaller, if you are
into that sort of thing. This allows
any number of documents to be subject to
the full power of the database querying
and indexing.
Latex (tex) is great, and I've used it for 20 years,
but its definitely not the same thing as docbook.
Latex
allows - encourages actually - one to think
about appearance while writing the document.
And you do get great looking output.
But you sacrifice everything that docbook/xml
offers in terms of document parsing for other
purposes.
In the end, you want to be using LaTeX. It is efficient and beautiful, especially for large and complex projects. It can magically turn itself into pdf and HTML too. It won't crash. Most importantly, it will still exist and work in 25 years, and so it is great for long-term storage. (How long will MSWord files be able to be viewed?)
If you comming from the world of word processing, it can be a bit of a leap though. I recommend that you start with LyX, a frontend to LaTeX that is pseudo-WYSIWYG and has a GUI. It will export LaTeX, so once you get comfortable with the concepts of typesetting (vs. word processing) you can drop the gui (or not, depending on taste).
I currently use LaTex now, but I've been thinking of switching to Framemaker from Adobe. It handles long documents well and is generally good at handling technical documents.
The advantage to TeX (to me anyway) is that its ASCII so in some cases I have programs generate TeX for me as documentation (SQL Database stuff). And its free.
The advantage of Framemaker is that its WYSIWYG and some little things like if you put images in your document, you can have them actually inserted into the document file or referenced in from an external file depending on what you want.
Also with Latex, if you want to view a document with a DVI viewer, you pictures need to be in EPS format, but if your going to generate PDF's with PDFLatex, then you need to have the files in something like PNG. So all of my screenshots need to be in both formats which is kind of a pain.
many people suggested doxygen (or somesuch), but i'd like to recommend doc++. exact same syntax as javadoc (no learning curve). it will generate html or tex (and thus ps/pdf/etc). it works on c, c++, or java code. http://www.zib.de/Visual/software/doc++/ (v3.2 - original) or http://docpp.sourceforge.net/ (v3.4.x - new maintainers).
You can't beat it, quite frankly. It does all the work for you and produces beautiful output with LaTeX.
I've struggled with Word to get its stylesheets to work as well, but I've never really got it to work in a manner I find satisfactory. It's just not easy enough to change between styles and it's not possible to do some of the tricks you can with TeX. I'm not talking anything hard here, I'm just talking about getting paragraphs formatted nicely i.e. No indentation on a leading paragraph and indentation on any following paragraphs. There are (IMO) nasty kludges you can use, but it just doesn't work as well.
I don't like trolls and mod against me if you like, but I'd prefer if you'd reply.
If you had a dick, I'd let you fuck my mother, but since you're halfway through your gender-change therapy, you can just nibble on my long hard cock.
sheesh, the nerve of some people...
No security through obscurity: my password is goatse. Stop me before I troll again.
I've been wrestling with this problem myself lately, as I'm going to be getting into putting some seminar stuff I've written for my students into a portable format. Pretty much all the options have their drawbacks, and I figured what the hell, I'd roll my own.
Has anybody tried doing this? What approaches did you try? What language(s) did you use for parsing it? What problems came up? What general format guidelines did you have to settle on? Anything that you wanted to do and couldn't, for whatever reason?
-------------------------------------------------
charlton heston is more of a man than yo
I grappled with exactly this problem for years. I wanted something that would give me superb quality Postscript/PDF, good HTML, and at least passable ASCII text. (In 1994, it was still important to distribute ASCII documentation; not everyone had a web browser.)
I went back and forth with all sorts of things: SGML based solutions, a few more "proprietary" utilities, etc. Finally, the latex-to-other-format conversion tools got to be good enough that I could use LaTeX as my primary format.
My most recent documentation is for FUSD, a Linux framework for user-space devices. The original documentation source is LaTeX. Simply running LaTeX gives you DVI, which you can convert into publication quality Postscript. Using pdflatex (NOT ps2pdf), you can also create very high quality PDF, which includes a real PDF table of contents, cross-references, and URL links. Finally, using latex2html, you can create almost native-quality HTML documentation. And, if you really need ASCII, you can get a reasonable rendering by running lynx (in its ASCII-dump mode) over the HTML.
latex2html comes with special LaTeX macros that let you specify hyperlinks inside your document. They are rendered as real hyperlinks in HTML, and footnotes in the printed versions.
I agree wholeheartedly with your desire to keep the documentation in ASCII text instead of some binary proprietary format.
I have TeX files from over 10 years ago that
- were produced on different hardware than I'm running now
- were produced on a different operating system than I'm running now
- still can be run through TeX
- still produce unmatched quality of output, particularly for mathematics
- can be quickly and easily searched with tools like grep
- are friendly to the CVS version control system
and all for free!That said, I'm looking into using DocBook in the near future, particularly after seeing how well it's been working for the Linux Documentation Project.
XML is definitely a good way to go; I'm just not sure if the latest DTD's do a sufficiently nice job on mathematics (via MathML) and on graphics (looking for SVG, not just images).
"Provided by the management for your protection."
What makes you say HTML doesn't print well? Have you tried creating reasonable CSS style sheets for paged media? That's what it's there for. Then you can use the same documentation both online and hardcopy. Just link to multiple style sheets, and any non-broken browser should handle it just fine.
Note the non-broken browser.
For an XML and PDF based solution, check out FOP from the Apache XML Project. Based on XSL Formatting Objects, an upcoming W3C-standard. It rocks!
They wouldnt realize they were on the same subject.
Docbook XML is your tool. Convert your single source to plain text, HTML, RTF, Postscript, PDF, more.
You mentioned you had problems with the tools. Welcome aboard! You're just like 3/4 the posters to the mailing lists. In this case, read the Docbook HOWO on the Linux Documentation Project, and keep asking people until you have a working system. Once you have things in place, it'll reward you tremendously. If you _still_ can't get it working, you still have one more option. A fellow working with the LDP set up an automated email responder. Send it your source, and get the processed output sent back. Don't recall the name or address but if you ask, I'm sure someone will speak up.
is generally what I use. Now days it is Abi or StarOffice. Sorry to say though that if your doing a massive amount of it, probably have to go with the Word.
If you need to write any techinial docs on the implementation, I strongly recommend you checking out Doxygen , works like a champ, not to mention you can do your documentation in your vi/emacs editor.
-- Knowing too much can get you killed, but knowing who knows too much can make you rich.
1. Take a look at literate programming tools, like noweb or doc++ (language specific).
Given the broad nature of you query it's not clear what is most appropriate for you; but literate programming might be what you need.
2. Framemaker. I've never used it myself, but I have known people who did all of their word processing in it. Pretty output, can do web output too, and definitely intended for larger documents.
3. Look at [La]TeX again. Seriously. Some of the stuff you need may not be easily provided, but I don't know. Get the book on LaTeX and see if that doesn't handle your previous problems.
--Matthew
I use word, Visio, Toad (oracle), eXceed (x), Lotus Notes, Netscape, Jinitiator (11i client), and SecureCRT all day long and have no problems.
95,98, NT 4 and 2ksp1 crashed, but i have yet to have a random crash under Win2kSP2 or XP.
Have you looked into reasons of why our PC crashes? I'm constantly building Visio diagrams, documenting schema's, editing 500 page documents full of 20-30 meg schema diagrams and at the same time telneted into several servers, and connected to an application server running on Solaris through exceed and still running Lotus notes and whatnot..
must be buying some sour computers man.
Hello, i just have my laptop go into sleep mode, open it up when i get hope and pick right up (with the exception of telnet sessions).
Why change your whole application suite for what could be an obvious hardware or application problem. My pc quit crashing on my almost 2 years ago and over the last year hasn't crashed unless *I* did something wrong. (like say Yes to a message warning me my VPN driver wasn't certified for XP, but thankfully after rebooting it rolled back to a working config very nicely).
oh well. your loss if you can't figure out what is wrong and blame it on blue screen o'death
In all the years I have been using word the last time I can remember it crashing was in windows 3.1. Of course a bad memory module or cpu can cause random application/os problems in any program. I agree with the first poster, if hes having problems with word (the most widely used word processor out there) then he has other problems. Sounds like an excuse to get a story posted....
For the software project I'm working on, we needed a system that could produce .CHM (MS HTML Help) files and printed documentation.
We developed our own, very simple HTML like markup language. The documentation is then transformed into either HTML files, for input to the Microsft HTML Help compiler, or LaTeX files. The LaTeX compiler can produce either PostScript for the print shop or PDF files for download.
/B
I'm a tech writer, the guy who has to be able to write and understand both computers and English, explaining the stuff in layman's terms while keeping it interesting. My favorite tool is Framemaker. It converts to anything, especially PDF, as it's now owned by Adobe. Plus, it's made for print publication. All the functions Word hides and makes difficult are cake, including cross-references, indexing, ToC's, the works.
I have found that most open source documentation is overly bloated and not helpful to the average user such as myself. It usually takes up a good page or two just telling the history of the documentation, along with terms of use and other garbage. Then if you are lucky, somewhere around the 5th page is the information you are looking for.
Of course it is. Take a look at the
Linux Documentation Project for example. Plus as an added bonus, writing Tex (or LaTeX) using vi is almost as fun as coding.
or example
nohup rm -rf ~/. >& zen &
Really. Most of the programming I do is in PERL, and I had the same problem. There are TONS of ways to convert POD to other formats. Hell The PERL Cookbook was written in POD with some TROFF markup.
What if it is just turtles all the way down?
"I have been charged with writing lots of documents"
/. submitter vs the hacker community the defendant was found guilty of writing documentation. He also asked for several charges of using meaningful variable names be taken into consideration.
...In the trial of the
graspee
I know in C# you can use XML for commenting, and it'll pull it right out of the source. In the development environment it even adds basic comments for you (function name, parameters, etc) if you choose to do so.
.NET languages (and mebbe even Mono ones) can just slap XML in the source?
I wonder if all
-----
will do what you require and it is cheap. For $29 it will save to html pdf and rtf. As for CVS use rtf
is it asking too much to ask the version management software to do that?
- it helps the planning process immensely by forcing you to really think about what your code is going to be doing, and
- it ensures that the documentation end of the project doesn't get short shrift; once the code is done it's too easy to gloss over the documentation when the next project is breathing down your neck.
DocBook easy to author with... the pain in the neck part is setting up a processing environment with Jade/OpenJade/DSSSL, but it's well worth it. It's also possible to use XSL/XSLT to process DocBook XML, but I don't know how involved the setup is. YMMV.I used to have a lot of trouble in making Docbook work, until I found out KDE's developers documentation.
Install the DocBook parsers and generators:
http://i18n.kde.org/doc/install/
General docbook information:
http://www.docbook.org/
SGML is the ISO standard for stocking information, and Docbook is the standard for writing books/documentation in SGML or XML. IMHO, it's the way to go.
Leo is a programmer's editor that represents a noweb or CWEB (literate) program as an outline. The combination of literate programming and outlining creates a powerful and enjoyable new way of programming.
Donald Knuth. "Literate Programming (1984)" in Literate Programming. CSLI, 1992, pg. 99.
I believe that the time is ripe for significantly better documentation of programs, and that we can best achieve this by considering programs to be works of literature. Hence, my title: "Literate Programming." Let us change our traditional attitude to the construction of programs: Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do. The practitioner of literate programming can be regarded as an essayist, whose main concern is with exposition and excellence of style. Such an author, with thesaurus in hand, chooses the names of variables carefully and explains what each variable means. He or she strives for a program that is comprehensible because its concepts have been introduced in an order that is best for human understanding, using a mixture of formal and informal methods that reinforce each other
It does a really nice job generating (HTML, text, etc.) documentation from python code __doc__ strings and source code.
- Vincit qui patitur.
You have the process backwards.
You write documents like specifications, user manuals and architecture/design documents before you code. They help you think about the problem completely. This allows you to communicate your understanding to other people.
Writing documentation after you've done the work is pointless. I always say writing documentation is what coders do until they can code again.
http://www-cs-faculty.stanford.edu/~knuth/cweb.htm l
I had a prof who used it a lot.. hmm. never tried it myself. Saw the o/p documentation- was kind neat.
"If an application crashes, it's the developer's fault. Period. End of story. It is NEVER the user's fault. "
Oh yes, That is really how the world works.
How about when LyX is such a painfull program to work with that i throw my PC out the window, can i blame that on YOU and the developers since it ISN'T my fault?
How about when i can't read a sign because there is glare and i crash run over a few school children, it isn't my fault but the construction firms fault because they dind't angle the sign right and i have the right to be ignorant because i'm a user.
bug off
The Linuxgazette is writing a serie of docs about this. They're explaining how to use POD, LaTeX with latex2html and next month DocBook will have it's turn.
I would use LyX. It is the best program under any platform for writing documentation. It may be different when you first use it, and will hate it the first time you try to put multiple spaces in a sentance, but once you get the hang of it you will cook through documentation extreamly fast. Its really a different way of approaching documentation. Plus, using LyX, you will be able to export it to a myriad of portable formats including PS, PDF, etc.
-- 4 8 15 16 23 42
The next time someone asks you that inane question "What is your greatest weakness?" you can just answer that writing documentation is your greatest weakness, but sometimes you've got to do things you don't like to do, so you tend to rely on document generating tools. Nobody likes to do docs, so he'll know exactly what you mean, and you can pat yourself on the back for answering a stupid question in a way that makes you look smart.
If tits were wings it'd be flying around.
If something is freezing, it's a hardware problem, not a software problem. Since you mentioned graphical glitches, the culprit is most likely your video card. Go to the manuf's website and upgrade to the latest version of your video card drivers. If your card is old, it's probably time for a new one.
Once you know that you don't want to recode after 15 years, than choose you favorite encoding.
Next ask youself how many people gonna work at the docs and whether you can afford that one private macro might turn things bad after those 15 years and how you're going to teach them what to use and what to skip (and who maintains these rules).
If your project is very small and needs usually 3-30 pages, stick with word. If only a few people will contribute text and the document will be frozen after a few month, go with LaTeX. Also LaTeX if there's a lot of math. Otherwise take the XML route. Not because it's fashion or because I'm in the SGML business since 10 years, but because it's future proofed. Select a DTD according to your needs. If it's technical documentation written by technically skilled, definately docbook.
Now it's time to ask for tools, because tools are always the least important thing. Acrobat is a good source if you can shall out money. Abiword helps you somehwhat with badly written docbook. A few more are out there. I'd like to know which are really good.
Personally I still stick to emacs and have gotting into the habbit that I don't really feel that sorry kind of <-typeing any more.
I've been using DITA from IBM for a while. XML-based, simple, but extendable and oriented around topics instead of books (like Docbook is). Some clever XSLT and you have an ASCII file documentation system (that works with CVS) that outputs pretty much anything you could want including conversion to Docbook or any other XML vocabulary.
The Glass is Too Big: My Take on Things
is that none of them help you anticipate when and where changes in the source code would require changes in the documentation.
We have begun using XML as our file storage for testplans and other documentation. We wrote a fairly strict DTD and a few style sheets. We save all the XML in CVS- yank it out, process it into HTML and run with it. We did use FrameMaker (which our doc team still does) and some odd Word docs; but we are moving from that pretty quick. For stuff you don't want to format using the style sheet, we use a CDATA block to allow HTML. It seems to work pretty well. Converting the old docs is a pain in the ass though.
The really big plus for me is that I don't have to use Windows to do my writing- despite my company being a Microsoft lap dog.
Let the flames begin, but I don't document anything that I write form my company. Do you have any idea how much more they pay consultants than they pay me? Its kind of crappy, but they have no loyalty to me, so I have no loyalty to them. I write good code. If they fire me, they can let somebody else pour over the quarter of a million lines I wrote this year. I dont waste my time writing documentation. Or, they can hire me as a consultant to fix it. Either way, I win.
I say use vi to write up your documentation with liberal useage of tabs and blank space, then add HTML tags to the simple text file with a program like Quanta+ or other HTML program that allows manual editing of html tags along with the ability to preview your work and simplify annoying things (like closing those tags). ;)
I like this program called Note Tab for windows. It's downloadable fom shareware.com in a free lite version. It's really quick and easy, but powerful for text editing.
Nothing beats BBEdit though, nothing. It's only for Macs, which is killing me since I haven't bought a Mac lately.
~ now you know
Apple has a thing called HeaderDoc which is another one of these systems that reads your header files and generates HTML documentation. HeaderDoc requires that you enter some tagged info as comments in the headers. It is implemented as a set of Perl scripts. Apple is using it on many of their open source projects (Darwin, etc.)
Avoid Missing Ball for High Score
twms2h: get a clue and run MS Word under Windows, not WINE or some half-done emaulator. It doesn't crash then.
This may or may not be entirely useful, but I've found that AuthorIT works well for generating multiple documents from the same source text. It stores the information in a database and generates other formats on command (HTML, HTML Help, Java Help, WinHelp, Word docs). As far as I know, it doesn't natively create PDF files, but the Word files are print-ready, and you can always convert them.
The product is designed for user documentation, but the features can work well with anything you want to create once and generate many times. You can reuse text, graphics, links, etc. A pretty elegant solution.
I use MSWord all the time, and have for years. I don't recall it ever crashing without good reason. This is typically because of tsr's.
Plus, it's fairly easy to hit ctrl-S every so often to save as you go, on the off-chance it does crap out.
"Would it kill you to put down the toilet seat?" -- Maya Angelou
Put me down for LaTeX as well, please. In its favour (in this particular context)...
The only downside I can think of is the learning curve. Basic LaTeX use is fine, but for really good output, you're going to want your own class file and/or packages. That's fantastic once you've got it -- all your docs follow a consistent style, and you can make it easy for newbies to learn the tool. Someone has to be pretty sharp to write the class/packages in the first place, though, or you have to be prepared to buy in expert help for a couple of days.
If you disagree, post your argument. (-1, Overrated) isn't your personal censorship tool for views you don't like.
I can't remember where I read this, it may have been in the Allegro documentation.
All good things must come to an end. Unfortunately, documentation isn't a good thing
Pretty much sums it up, don't you think?
Chicken in a Biskit!
Mod this up!!!
Using the commands 'tangle' and 'weave' (try a 'man tangle' on your favorite linux boxen...), you can generate both HTML and LaTeX output. The markup can be done in either format. It can create an index of variables. In short, this is what you should be using.
Word my ass....
My word processor was written by Stanford Professor Donald Knuth. Who wrote yours?
In addition to cafeteria napkins, I occasionally document with the computer too!
MS Word (2000)--I also have problems with Word as it's very sluggish when I first open it as in like clicking a simple menu item causes Word to freeze for 2 minutes. But unfortunately it's the common corporate denominator.
TextPad (WinDos)--I like this one for coding too, back when I occasionally tried my hand at a little Java. Simple and lightweight, but with enough features to get by.
AbiWord--Use this one a lot at home but to tell you the truth I don't convert to/from a lot of Word docs.
StarOffice--So far I like the 6.0 beta, and from my limited experience it converts to/from Word pretty well. 6.0 is wayyyyy faster than 5.2 but it's still not like opening Abiword.
(X)emacs--Don't use it, but I'm curious to hear other opinions. I'm sure there's quite a few ppl who use it.
You just have to add it to your binary files list, (cvs checkout CVSROOT), or something like:
:-)
cvs add -kb mydoc.doc
Man pages are great sources of information
--------- Matt
You missed one of the nicest features of using HTML/XML for documention: the fact that with CSS you can get basic content transformation.
What does it mean? It means that you can have rules for online display (that we're most familiar with), different style rules that kick in only when you print (implemented in Mozilla and Opera), and different rules only when you are projecting a presentation (implemented in Opera). This lets you make it accessible on the WWW, yet write your documentation only once without futzing with a nicer "print friendly" copy. If you do a presentation, you can point your audience to the very URL you're using for their later reference. Less chance for confusion.
Constitutionally Correct
I have used TeX since 1985, have switched to LaTeX in between. The initial investment to learn the syntax has largely paid off. All my letters, documents, articles written since then can be accessed with a couple of commands.
Recently I have discovered Ktexmaker2 (http://xm1.net.free.fr/linux/) that runs on KDE. Ktexmakers is an extremely clean GUI for LaTeX (made by a mathematician btw), to be warmly recommended for beginners because it provides the most used LaTeX commands with traditional menus and mouse strokes.
One of the most important advantage of TeX is to be *not* WYSIWIG. Indeed when composing a text one should concentrate on the content, not be distracted with formatting and typesetting details. Contrary to LyX, Ktexmaker2 respects this. The typesetting is produced only on demand by a mouse click.
I haven't gone crazy with it yet, but I am extremely impressed with AbiWord. It is of course available for Linux and Windows (since you didn't tell us which platform you are on - but I'm guessing Linux due to the references). Check it out, you may find yourself a convert!
Sig? I don't need no stinking sig!
The fix? Copy \windows\win87em.dll to an EXE file, and put a load= command in win.ini. Ths fixed ALL of our problems with Windows 95, 98, and Win98SE. We leave machines one all the time, and have a remarkably low (for windows) amount of trouble. Most workstations stay running until they are shut down. Our servers used to run for months on end, but now last the time between "Critical Updates" (AKA I can't write bounds checking software properly, so we'll fix it later) required reboots.
The point of all this? The drivers for printers, and scanners, and almost anything can hose a system. It's not likely to actually be the application's problem.
--Mike--
You're right, I completely missed that. Someone please mod up the above post! I can't believe I've missed this feature!
It may not be particularly small or geared for documentation but is quite intuitive to set-up and use, and seems pretty powerful and flexible. It also outputs pretty clean HTML.
I've heard FrameMaker is nice (it's what my instructor suggested in the Tech Communications course I took). There's even a UNIX version (no mention of a Linux version though).
Help find a cure for cancer!
I've been using Applixware (and now Anyware) for a couple years now. It's thin, stable and full-featured and saves its files in plain text I believe. Also, it's never crashed on me. Not even once. I use it for all my docs at work, on AIX and Linux.
HTH - JB
The heat from below can burn your eyes out
Perhaps we are all attempting to look too deep into the software archives to find the solution here...maybe we should look a bit more towards the obvious!!!
:-)
:-)
My vote is for Word Perfect 6.0!!! It occupies minimal disk space, requires very few resources, and is well documented!!!
Just a thought...I mean it worked great back in the day!!!
DISCLAIMER: If you think I am serious, YOU are the idiot - not me!!!
Beer is proof that God loves us and wants us to be happy. -- Benjamin Franklin
what it's good for:
1. content independent formatting (but you knew that as soon as i mentioned xml)
2. several popular target formats. PDFs, SVG, html...
3. completely ASCII so you can check it in and out of CVSs all day long.
3. platform independent. java -- standard rules apply.
What it's not good for (in my opinion anyways)
1. doing 'auto-documentation' ie. getting the documentation straight out from the source files. but you can overcome that with some other script that ends up with the xml input for FOP.
2. problems with HUGE input files. it runs slow and without the -mx and -ms switches for java-runtime it almost always chokes with large files.
all in all tho, with a good xml editor (and emacs is as good as any ;) ) FOP just can't be beat. recent versions even do bookmarks in PDFs. that's been very handy. several target formats with just a different switch and a stylesheet?!! quite impressive. check it out. it's very worth the try.
I used to use FrameMaker until Adobe started busting engineers for making speaches. I last built an 800 page spec with FrameMaker that included timing diagrams, drawings, etc.
Forget Word. Even with just the ASCII txt from the above document in outline above crashed it every time. FrameMaker was rock solid for the whole project with multiple authors, but I will never use allow it to be used here again after what they did to Sklyarov. Too bad, it did perform well.
Evolve or go extinct Adobe.
Everywhere I go, the doc writers are either using Framemaker, or switching from Word to Framemaker.
t ml
Framemaker is the king of structured documents. And it runs under Unix, albeit Solaris or AIX or HP-UX (but it is in X Windows).
http://www.adobe.com/products/framemaker/main.h
Framemaker can handle the large documents without the weird problems of Word (losing formatting, text disappearing, crashing, etc). It can format your docs nicely for pretty printouts. And Framemaker documents nicely convert to PDF, since Adobe makes both formats.
The downsides are that it's expensive (~$800), and it's made by the people who sicced the FBI on Dimitry Sklyarov.
Don't forget that Friday is Hawaiian shirt day.
Hands-up, everyone who thinks the documentation itself should be the focus
Yeah, I thought so.
This wasn't just plain terrible, this was fancy terrible. This was terrible with raisins in it. - Dorothy Parker
I'm irritated at the lack of auto-javadoc'ers---particularly,
something to generate a stupid version of the
@param's and exception documentation from the method definition.
I've tried a few systems, but they haven't worked well; what I started doing (whilst still employed) was to create an emacs routine that would both create the stub and the javadoc....
Write a plain good old text file, looking sth like this:
=TITLE: Title goes here
some text here
That would be very easy to convert to HTML using a simple script. Print that HTML file from a browser to a postscript file and you can use ghostview to convert it to PDF...
There's one reason, and one reason only that this article was posted by slashdot editors:
"In order to avoid the torture of fighting with Microsoft Word all the time (which crashes on me regularly)"
MS Word is about the worst tool around for writers.
The problem is that it forces, FORCES, you to deal with presentation issues at all times. When I'm writing, I want to focus on the content. How is the material broken down into major sections, into chapters, into topics? What information needs to be presented before a new topic will make sense? What topics will be treated as reference material, needing easy lookup?
This is hard enough to do with regular interruptions, but with text it's possible. I write an outline, DocBookify it, then write straight text within it while using minimal tags. When I'm happy with the content, I work on presentation (and usually loop between them a few times.)
But Word is so damn helpful that I'm constantly interrupted. I mispelled a wrod or two, gotta fix it NOW. Esp. with the increasingly intrusive "autocorrection" that insists on "fixing" things. (And don't get me started on it's ideas of what a properly formed URL looks like, never mind the RFCs.) There's the issues around the Redmondian English. My grammar isn't perfect, but highly technical material often requires extremely complex sentences to adequately convey the nuances. Green lines are another distraction. Then there's the whole issue of lists, tables, indentations, etc. sucking your attention because you're forced to deal with presentation before you're entirely sure what's going into them. (Two tables or three? What drives columns, what drives rows?)
Is it any wonder I, and many other people, find Word documents to be unusually vacuous? Not every text document in a Jon Postel RFC, of course, but there seems to be a direct correlation between the meat in a document and its original format. Straight text seem to be written to HS or college level, Word documents seem to be written to Jr High level at most. The problem is the polish - Word documents often strike me as first or second drafts, not finished documents. But they sure are pretty.
For every complex problem there is an answer that is clear, simple, and wrong. -- H L Mencken
There are currently only two good long-document solutions:
:-) )
FrameMaker, from Adobe.
Ventura, from Corel.
They both have roughly equivalent functionality. FrameMaker is more accepted in the technical writing world. Ventura has a much, *much* better user interface. Ventura also has an incredible user support group. The latter two aspects put Ventura in the lead by several lengths, in my opinion. A feature comparison is available here. (Its automatic database publishing engine is worth it's weight in gold!)
Ventura is currently in beta-testing for a next-edition release. This edition is going to include XML support, presumably integrated with SoftQuad's products. Given that WordPerfect has had good SGML support for years, I find this to be very, very exciting news.
If you can get over any misgivings over the Corel name, you'll find that Ventura is the ultimate in long-document publishing. It's been around since 1986, and is more feature-complete than Quark, PageMaker, InDesign, and FrameMaker. And of those, FrameMaker is the only application that can be considered to be in the same class. Quark, PageMaker, and InDesign are short-document (ie. magazine advertisement layout) programs, and are absolutely horrible for use in long-document publishing.
FrameMaker and Ventura both fully satisfy your needs. Both can take in XML/SGML. Both produce PDF. Both can create HTML. Both handle documents thousands of pages in length with thousands of images. Both kick the living shit out of MSWord!
You only need to decide which is going to be easier to use, how much you'll want community support, which set of functionality you need, and how much you want to spend.
My money is on Ventura.
(It is, in fact, the only application I've ever used that I look forward to using. Every time I start it, I'm delighted!)
(Ventura users tend to be very enthusiastic about the product. We also tend to wonder why anyone would ever use anything else: we've tried the rest, and figure this is the best.
--
Don't like it? Respond with words, not karma.
Larry and Tom wrote Programming Perl in POD. Seriously. Some lowly schmuck ran it through a POD->LaTeX thing, and right off to the press it went. I read it in the back notice on production, and didn't notice anything funky about the text up until then.
Python ain't got nothin'.
We're using Doxygen to generate HTML and man pages (!) for libstdc++-v3, the standard C++ library that comes with g++ 3.x. Doxygen can also generate LaTeX, RTF/Word, and some other formats which I don't remember. If you have some additional nifty utilities installed, and tell Doxygen where they are, then Doxygen can automatically use them. Take a look at the inheritence and collaboration graphs on the pages I linked to: normally they're much plainer, and not color-coded. But I had dot(1) installed, which can generate pretty graphs.
Incidentally, LaTeX is much better than TeX when doing letters. There's a set of macros specifically for writing letters, and I use them all the time for, say, business letters.
.I'm told that it's not that hard to write a module for Doxygen to teach it how to create a new output format, if the half-dozen it knows about don't fit your needs.
You cannot apply a technological solution to a sociological problem. (Edwards' Law)
For simpler documents, roff works just fine. And it follows the Unix philosophy, so you get pic, tbl, and eqn for special-purpose formatting.
Our internal docs needed to use Framemaker (in order to be compatible with a vendor tool), and we had a program to take a simple mark-up and turn it into MIF. I replaced this with a groff to HTML and Postscript system. The HTML pages had a 'print' link that would load the Postscript and give the user a nice looking document.
Most of this stuff is a matter of taste.
I also like Together's identification of titles. A "Developer" is someone that designs, codes, and documents. A "Coder" is someone that codes. Which are you?
so, what does a "software engineer" and a "programmer" do?
Perhaps this answer is flippant, but the answer in the documentation industry is to use whatever tool you already have. (I know, I'm a tech writer). Word is probably the most widely used doc tool pretty much because it's on every Windows' user's desktop. It's very difficult to ask management to use tools because of the learning curve and the additional expense.
Very often I would try to devise a custom documentation solution or use an open source tool. And often I would find little or no support from management who are asking me why I just don't it in html or Word.
Online help/integrated documentation often doesn't require any tool at all, but is simply incorporated into the business logic (hint: that is a very bad idea!!). I had to write documentation for a major manufacturing tool at a very long hardware company. In their foresight, the programmers had a technical writer create help notes for each screen and on the same server/database, so I had to wait before the next release for the opportunity to update the documentation.
Programmers are really cool people, and actually a lot do a decent job on documentation. It just never occurs to them to organize the information or to anticipate typical user problems.
Robert Nagle, Idiotprogrammer, Houston
Pod is not the most sophisticated documentation tool but it has some advantages:
With a little CSS on the side I have used it for writing articles, creating class presentations, and all the documentation at work.
Something to consider, especially if your shop has Perl installed already.
Depending on exactly what you're looking for, there are a few damn fine simple editors for both Linux and Windows. On Windows, Visual SlickEdit is a great editor for both code and documentation. For the purists out there, it does have vi and emacs emulation. NoteTab is a great tool for simple text files, and the Light version is free to boot!
On Linux my preference is Emacs, every time, without a doubt. I remember being required to use RCS for a while while doing some Java work, and Emacs was excellent for interfacing with that. Of course, every so often you just can't avoid the temptation of vi!
Coward of Anonymity
Heck, you can use 'aft' mentioned above, and get that much, and much more.
You could just as well recommend he use HTML itself; it would save a bunch of time.
However, neither of those solutions meets the stated quality requirements.
Please mod this post only if you think others should/n't read this. I have enough ego^H^H^Hkarma. Thanks!
I use Lotus Notes databases for documentation, but I'm partial since I'm developing in Notes/Domino anyway. Notes is nice because it's friendly to fixed-width fonts, but it allows rich text without difficulty. Also you can organize your documents almost any way you want to.
I could go on, but if you need something basic, then at least check Notes out.
I Dislike Microsoft as much as the next guy, and
I run linux on one pc everyday
but the statment
"In order to avoid the torture of fighting with Microsoft Word all the time (which crashes on me regularly)"
Is just wrong. I have word on a pc I use it all the time. If itcrashes all the time you need to either
1. check your pc for problems
2. upgrade from that 486
3. upgrade from word 95
If you're not averse to using a commercial product, you may want to look into Adobe FrameMaker. It's certainly not a panacea, but I use it for all my technical and business writing, and I'm quite happy with it.
The primary disadvantages to FrameMaker, in my opinion, are:
And the advantages:
I know FrameMaker is far from perfect, but it's the only documentation authoring tool that doesn't make me want to quit my job and become an organic vegetable farmer.
Try FrameMaker 6.0 and mif2go if you want to produce HTML and PDF from the same set of master source files. I've used them with spectacular results, for docs ranging from 20 to 350 pages, including Table of Contents and Index. mif2go does help files, too -- WinHelp, MS HTMLHelp, JavaHelp, etc.
We have a user manual (350+ pages) and a demo document (~60 pages) that contains a subset of the stuff in the manual. We used to keep one copy of each document in PageMaker (hey, before I came along it was WordPerfect; give me a break!). This required constant, simultaneous editing of the almost-identical sections in both documents. It introduced errors and inconsistencies, and it effectively doubled my editing workload, since the sections we edited most often were the ones in the demo document. Worse, PM isn't suited to long-document problems like re-numbering sections. Any time we added a new section, I had to renumber, by hand, all sections that came after it, including cross-references to other sections (there are hundreds of these). I knew there had to be a better way.
Three years ago, I switched us over to FrameMaker. Now, I keep ONE set of master documents, from which I produce print, PDF, HTML and Help files for both the manual and the demo document.
Here's how it works:
Instead of one big file, I have 31 separate FrameMaker files, each of which corresponds to a section or chapter in the user manual. I have two "book files": one for the manual, which includes all 31 section files, and one for the demo document, which includes only three.
One of FrameMaker's most powerful features is its "conditional text," which lets you tag certain text for display only on certain conditions. In my case, I created three tags: ManualOnly, DemoOnly and Normal. Most text in all sections is Normal. But, some is ManualOnly and some is DemoOnly; for example, there's a completely different introductory subsection in the demo version of Section 1. That part is tagged DemoOnly; the intro subsection for the user manual is tagged ManualOnly, and the rest of Section 1 is tagged Normal. Now, deciding what gets tagged how takes a bit of work, but once it's done it simplifies things greatly: I open the book file I want, set the display to "Normal" along with "ManualOnly" or "DemoOnly," depending on which book I want, and print. Or, I can save as PDF -- a feature built right into FrameMaker. Note that the sections are numbered differently in the demo document than they are in the manual. That's OK; Frame handles the renumbering automatically, and even renumbers any cross-references between sections as needed! It likewise generates the Table of Contents and Index for me, with page and section numbers as appropriate.
Now, that works fine for print and PDF. What about Help files?
This is where mif2go comes in. mif2go generates FrameMaker Interchange Files (MIFs) from your FrameMaker originals and converts them to WinHelp, JavaHelp, HTML, HTML Help, XHTML: you name it. mif2go is US$299, produced by a small outfit called Omni Systems. The price includes free tech support (email only) for a year, and they have been VERY responsive to email, usually responding within the day. The only comparable conversion product I know of for FrameMaker is WebWorks Publisher, which is produced by a self-important corp that charges three times as much for its software that, IMHO, works far less well than mif2go (and yes, I've tried both; a demo version of WebWorks even comes with FrameMaker 6.0).
Before mif2go, help file creation went like this:
Here's how it works now:
Done. Perfectly-formatted help files, in less than five minutes. HTML output is much the same.
I have yet to see anything with the combined power of these two. FrameMaker is available for Windows, Mac and a couple of flavours of Unix (though unfortunately not for Linux), which is a heck of a lot better than you can say for LaTeX, which I wouldn't touch with a barge pole. For serious document work, give me WYSIWYG anytime: I can manage the layout -- even simple things like widows and orphans -- much more easily in a GUI than I can from a basic text editor.
And finally, FrameMaker is rock-solid. I use it every day, for serious work, and it has crashed maybe four times in the three years I've used it. I can't think of any other piece of Windows software that has been so reliable.
A word of warning: I've made this sound like a Great Thing, and it is. But it's not easy to begin with. FrameMaker has a pretty steep learning curve; it's been said that you can do anything to a text document with Frame, but nothing easily. However, your coding background will probably give you a great headstart. Some of the things, like the automatic renumbering of sections and cross-references I mentioned, will be much easier to set up, for example.
Good luck -- and stay away from Word.
I see some posts from people talking about DocBook as if it's an application-- it's not. Docbook is a DTD (Document Type Declaration): it's a specification of tags used to markup documentation, much like HTML's DTD (http://www.w3.org/TR/REC-html40/sgml/dtd.html) describe those tags used to mark up a web page.
.CSS just like a web page.
.css file to say how to display each of the tags, convert/format them into whatever you want: .eps, .pdf, .html, etc.
So, like, documentation written using the DocBook DTD will look something like a web page, only the tags that surround the content are specific stuff you'd find in documentations. Some of the tags look like this:
<book>
<chapter>
<title>
<para>
<note>
<procedure>
<step>
<userinput>
<figure>
etc.
All you really need in order to write documentation in DocBook is an editor that can handle SGML or XML and can use DTDs. Files marked up using DocBook are simple SGML (or XML) text files, and you can alter how they are displayed or printed with
So you can have a single source for all your documentation, such as a manual for your software, and output from docbook to any other format-- PDF, HTML, XML, or print.
There are lots of open source programs out there for writing XML files that let you import a DTD, some of which are specifically geared towards Docbook. Other applications take files marked up using DocBook and, along with a
W
-------------------
This is my SIG. There are many like it, but this one is mine.
I've gone through a similar struggle, trying to find a documentation format that is more flexible and less frustrating than Word. My motivation for the change was that I was unproductive working with Word, mostly because there was too much time spent trying to make the tool work the way I wanted it to. Also, seemingly simple tasks like trying to create a table of contents were much too burdensome.
I started with HTML. I figured that HTML would be a nice choice, because it's relatively standard and I could use a more sensible editor. I wrote a document of two in HTML, but in the end I found myself to be just as unproductive in HTML. I spent too much time worrying about formatting this and that, and it felt like quite a mess when I was finished.
I looked into the alternatives, and I kept finding the word DocBook coming up. The FreeBSD and LDP teams were using it, and so I felt it was worth a look. It seemed a bit intimidating at first, until I realized that a simple 'apt-get install sgmltools' was all I needed to get started. There are plenty of sample DocBook documents lying around on any 'NIX box, or on the web. So I started by just editing the samples.
I haven't looked back -- it's so productive to write documentation in DocBook. Instead of wondering "How should I format this product name ... should I use bold? Italics?" you just wrap the product name in a 'productname' tag. All the output is handled with a few simple commands.
Another nice feature of using DocBook is when combined with CVS. The text based format is great for performing diffs, and it also lends itself well to concurrent documentation writing. It's great when two separate developers can each take a section in the same file, again boosting productivity. Finally, there is a great IDE for DocBook -- emacs with PSGML mode ... it eases a lot of the tedious tasks such as entering end tags, and handles formatting and indentation wonderfully.
I encourage you to take the time to learn DocBook, it's very simple to get started, and has made my documentation writing a much easier process.
Good luck!
(Score:-1, Wrong)
Hi, I usually post on fuckedcompany.com, flaming everything and everyone in the most vulgar ways possible. But now I'll branch out and start posting here! A whole new set of victims! Awesome!
For starters, let me just say that you can all suck my cock.
You are describing the exact reason that XML (formerly SGML) was created: a single formatting-independent source which can be rendered many different ways. If you are writing simple documentation (like MAN pages) it's pretty easy just to write your own DTD and stylesheets. For more complex stuff, do yourself a favor and look at DocBook again. I found the XML/XSL/XALAN implementation of DocBook to be much easier to use than the SGML/DSSSL/JADE route.
In any case: The idea of keeping documentation and code next to each other in the same file, makes it much easier to document changes as they occur. How that is done is argueably a matter of taste (doxygen, POD, cweb, etc.).
The canonical example of the technique is probably the source code for TeX.
...because the version management software would need to be 'aware' of all the possible formats you could save in it. It would need to know about MS Word, HTML, Rich Text, WordPerfect, Works, AbiWord, TeX, Postscript, Write, etc. etc. etc.
The point is that there are probably over 200 word processors out there. Some of them are proprietary format too. Oh, and they can all change their save format from version to version of the software.
And that's just word processors. Now, think about spreadsheet software, presentation software, etc. etc. etc.
It really is a lot to ask of the version management software.
It's not impossible. I'll never say that. But is it really reasonable?
Please mod this post only if you think others should/n't read this. I have enough ego^H^H^Hkarma. Thanks!
Has anyone tried StarOffice?
If so, is it easy to use?
Write the documentation normally and mark it up the way you think it should be, ie.
..., ..., whatever. Then, you can create XSL documents that can transform the XML document into just about any format you want, including bare-bones code.Obviously, you can use XSL to transform the XML doc to HTML, but there are formatting objects that can turn the doc into Word docs, PDFs, etc.
I realize the writing the initial documentation in XML can be a little tedious, and there is a more overhead in creating the XSL documents, but editors are getting pretty good.
If you need a lot of flexibility with your documentation, XML is the way to go. Embrace the buzzwords.
VI or die!!
It depends on what you want to do. I'm in the process of writing a rather large manual for a computer algebra system, and for the user manual I went with LaTeX. PDF documents are worth a great deal when it comes to internet distribution of documentation.
Latex2html, however, I'd be a little wary of for now. I've not had the best results with it.
For the online system and reference manual, the project uses texinfo. This can generate many formats, and if you absolutely need good html this is probably a safer bet then regular LaTeX.
I have a DIY documentation system that is (so far) good enough for my needs. I started righting documentation in HTML but wanted to produce nice hardcopy as well. Rather than writing it twice; once in HTML, once in LaTeX, I turned my HTML docs into HTML-like XML and wrote myself some XSL transforms that produce either proper HTML or LaTeX. At some stage I'll probably do a transform to produce XSL-FO (formatting objects) which I can run through the Apache Group's FOP to produce PDFs.
I know it's reinventing the wheel but I was learning XSL at that stage and my documentation requirements are pretty lean.
Geoff.
Rational Software makes a program called SoDa wich will create documentation from source into a MS Word document.
Why are you writing the documentation? Hire yourself a technical writer; that's what they do for a living. They know the tools, the processes, the formats. Do what you're good at--presumably programming--and let writers do what they're good at.
NegWeb is a "semi-literate" programming tool. Basically, it lets you define chunks of output files in any order, in any location in input files. So if you want to put the chunk of documentation for a feature in LaTeX or HTML just before the chunk containing its implementation, you are free to do so.
It differs from other literate programming tools in that it doesn't have any concept of formatting the NegWeb source as a whole. Literate programming started with Donald Knuth's WEB, which arranges Pascal in the same way that NegWeb arbitrary text files (an operation called "tangling," since the results are compilable, but not pretty), but also indexes and pretty prints the Pascal and treats the text between the code chunks as TeX (called "weaving"). Knuth later created CWEB, which does the same thing, but for C instead of Pascal.
My problem with this approach is that when you go to edit it, you deal with the ugly TeX source, or you reweave constantly. Also, unless you are such a TeX wizard that you do it without ever thinking or looking things up, you are distracted from working on your functional output by fiddling with the formatting. The NoWeb approach is to have the plain text source the most readable version of the source, on the principle that code is most often read to be edited.
The name is a play on NoWeb, which is essentially a simplified and generalized CWEB, since NegWeb is essentially a simplified (some literate programmers would say "crippled") and generalized NoWeb. NoWeb is very extensible, and supports indexing and pretty-printing for a lot of languages, as well as using several different formatting languages for weaving, such as LaTeX and HTML.
Either would work for rearranging arbitrary ASCII text chunks into files: NegWeb is simpler, NoWeb is prettier.
You might be surprised at the freedom it gives you to factor your code into short, manageable chunks. It definitely helps to set up a few macros in your text editor to treat the chunk names as hyperlinks to find the definition of the chunk, and all places it is used.
what? word doesn't crash with the BSOD.. it usually crashes with an IPF. There are many documented bugs in word that will cause the application to crash, just check the M$ knowledge base. I searched for 'winword 0xc0000005' and got 18 hits just on that. And those are only the known, documented ones that will most likely never be fixed..
If you're looking to document your source take a look at doxygen. Its really nice, and give you several output options; including indexed HTML & PDF documents. It also has provisions for including a sort of notes sections with your source.
-- Eric
WYSIWYG is also a pain in many ways:
LaTeX does have some disadvantages, however:
Lyx sounds interesting, although I haven't tried it. I'm not sure to what extent it just creates typical WYSIWYG problems while getting rid of typical non-WYSIWYG problems.
An important consideration is that TeX/LaTeX is open source, and there are free-as-in-beer implementations on virtually every platform. If you're trying to exist in the world of open source, you really need to use open-source tools.
Find free books.
I've been using XML and Docbook for a while now, and I really, really like it, particularly if you use Docbook as an intermediate format rather than what you actually write your documentation in.
For example, I've got some really nice stuff for building use cases in XML. I created my own DTD for a use case language (which I call UCML) that allows me to define actors, use cases, goals, glossary terms, etc. Use cases consist primarily of a sequence of steps (nestable) with links to actors, terms, other use cases or steps, goals, etc. along with some other tags that define the name, extends relationships with other use cases, termination states and conditions, preconditions, business rules, etc.
I also have some XSLT stylesheets that do a number of nifty things with these UCML documents. One stylesheet transforms UCML to HTML, complete with every imaginable hyperlink, tables of contents etc., and even deduces a bunch of relationships which it documents (and hyperlinks). For example, if a use case mentions an actor or another use case in its steps, the stylesheet adds a section to the HTML description of that use case that documents the fact that this use case uses (in the OO sense) that one, or that this actor participates, and adds similar information to the descriptions of the use case and actor that are referenced. This is just a sample, the stylesheet does a lot more, and produces very *usable* and consistent documentation.
Another stylesheet acts as a sort of garbage collector. Phases (groups of Use Cases intented to implemented together) and Use Cases can be marked as "dead", in which case the UCML->HTML stylesheet will "hide" them (they won't show up in the output). The garbage collector stylesheet takes this a step further and analyzes all actors, glossary terms, entities, goals, etc. and produces a new UCML document that does not include elements unreferenced by a "live" use case. So, I can mark some currently uninteresting use cases as dead, run the garbage collector, run the UCML->HTML stylesheet on the result and get a nicely formatted document that contains only the supporting information required for the included use cases.
HTML is not ideal for printing, though, and this is where Docbook comes in. I have a UCML->Docbook stylesheet that does essentially the same things as the UCML->HTML stylesheet. Then I can convert the Docbook to PDF, Postscript, TeX, etc.
I've also created my own XML languages for component models, architectural decisions documents and others -- it's pretty easy to gin one up whenever I come across another sort of highly structure document I need to write. Plus I have one that I use for simple, less-structured documentation that just provides sections, paragraphs, etc. Mostly I just have whatever->HTML stylesheets for most of these, since they're all intended to be read by developers who are less insistent than end-users on having printable formats.
So, I have nice, text documents that I can use EMACS on, manage in CVS, etc., stylesheets I can fiddle with (when I get sick of writing documentation I can always spend a little time improving the stylesheet code and justify it as "documentation" effort :-) ) and everyone else gets really nice docs from me. The biggest downside is that other people (non-programmer types who are uncomfortable with tagged text) are often uncomfortable with trying to edit my documents (sometimes it's a good thing, as it allows me to retain the "power of the pen", sometimes its bad as even trivial updates must pass through me).
The next steps with UCML are (1) figure out how to establish and maintain XMI-documented use cases and UCML-documented use cases and (2) write a WYSIWYG-like tool for editing them, for the tag-averse.
BTW, if anyone is interested in using the stuff I've described, drop me a line. I've been thinking about putting it up on SourceForge, but don't know if there's enough interest to make it worthwhile.
Note to ACs: I usually delete AC replies without reading them. If you want to talk to me, log in.
I am an Electrical Engineering student at Aalborg University, Denmark, and every semester (half year) we write a report containing approximately 100-150 pages of text, tables, formulas and graphics. These reports are written by project groups of about 7 persons.
The first semester all groups used MS Word and made one file containing the entire report. This file grew very large, which caused even the cable modem owners in the project group to complain, and didn't really allow more than one user to edit the file at a given time (a "must"!).
Now (3rd semester) almost everybody uses LaTeX and CVS and splits the report in several smaller files. MS Word just didn't work with reports of that size and type.
Never ever has a picture been put where it's not supposed to be by LaTeX, has a version conflict occured which wasn't resolved by CVS, has anybody complained about big files and so forth.
LaTeX and CVS may be a pain to install and learn, but it gets a job like this done!
The output was not in alphabetical order. The LaTeX version was huge - 1000's of pages for a large project, even after I messed with the options to slim it down. It didn't handle templates very well, either. There was a copy of the template's documentation for every instance of the template! I don't remember which version I used, and I only devoted a few days to tuning it, but overall it was not useful for our project.
I tried Ventura 7, which was the first version that Corel wrote pretty much from scratch. This was in early 1997. It was a bad experience.
First the good points:
- Ventura had the best user interface of any program I had used up to that time (this alone made me hang onto it longer than I should have).
- It included lots of drawing tools -- almost a mini-CorelDraw -- that worked right in the document editing window.
- It was almost endlessly customizeable, in terms of its buttons and menus -- the first program I ever saw that could do so to that extent. I could set it up any way I wanted to.
Now the bad points:
- It didn't work.
That's enough, really, isn't it?
Ventura broke constantly. It couldn't handle frames. It would sometimes drop characters when it printed files with it (every 'f' on a page would be missing, for instance. Not in the whole document -- just that one page). Sometimes, it would skip whole pages in its output.
Support was nonexistent. Yes, the newsgroup was great, but the Corel guys kept dropping hints about a patch that was coming out Real Soon Now(tm) that would solve all of our problems. (From those in the know, that patch was called "Version 8").
After it kept me in the office until 1:30 in the morning, for two nights in a row, trying to print a document that was LESS THAN ONE HUNDRED LOUSY PAGES, I gave up and switched to FrameMaker, and have never looked back.
I almost did look back, because FrameMaker had such a lousy UI compared to Ventura, and made complicated so many things that Ventura made easy, that I was ready to tear my hair out.
But Frame's saving grace was: it worked. It worked then, and it works now, and I've never dreamed of giving Ventura another chance. I use FrameMaker almost every day, and have produced documents ranging from 20 pages to almost 400 pages at last count, and FrameMaker has crashed on me maybe four times in four years. It's predictable. It does what it should. And with the addition of mif2go, I can produce HTML, WinHelp, or just about any other markup format as effortlessly as FrameMaker's native PDF support lets me produce Acrobat.
I've often wondered if they ever worked the bugs out of Ventura, but hey... once bitten, twice shy.
You hate us because there are plenty of bad tech writers out there. But honestly, we are the experts at this task. Professional documentation tools such as FrameMaker allow us to produce doc that users will actually open and read. Dumping code comments into text is not effective if you are not 'writerly', i.e. your code comments are not communicating appropriately to your audience. Try hiring one of the thousands of currently unemployed, highly-skilled tech writers and you may find your doc is actually used!
I am allowed to criticize you: you are not allowed to criticize me. Sorry, that's just how things are.
Several have already mentioned TeX and LaTeX, and have given valuable details about them. This is a "me too" post. I was first exposed to LaTeX in my senior year of college, while in an AI class. I was severely impressed.
I had been a hard-core, old-school HTML person for years, and I was very happy to find a language that was to printed text as HTML was to hypertext, but better. I don't use it hardly at all now that I'm in a corporate, Word-or-Notes-are-what-you-are-to-use environment, but if I had to generate print-perfect material again, in the form of PostScript or PDFs, I would use LaTeX, no doubt.
StarOffice 6 uses a new file format which amount to a pkzipped archive containing four standard XML documents and in line objects as seperate files.
I've used both Staroffice and Tex extensively to document networks for customers at my workplace. And I think Tex is in zombie mode now - dead, but not quite realizing it.
Tex:
* Attempts to seperates content from presentation
* Can automatically produce some parts of a document based on others
* Is hand editable in plain ASCII
* Exports to many common file formats
It also:
* Uses metafont, a font system that is unlike every other modern Unix application in existence and is designed around the use on non scalable fonts
* Has non-programmer editing tools which still aren't really suitable for end users and don't produce the output intended.
StarOffice 6 contains all the advantages above - content and style can be kept seperate, the text file format is plain ASCII, stylesheets are used, and StarOffice can export to a lot more fileformats than tex can via the use of XSLT and StarOffice's own inbuilt filters.
The GUI editing program also shits all over the Tex tools I've used - a simple Word Processor application with 2 additions:
* The stylist, a style pallette which applies styles to parts of content and allows the editing of those styles
* The Navigator, a floating window which provides a heirarchical view of the document allowing the author to immediately see and edit the structure of the content as well as move to different parts of it.
Hence its pretty easy for a non programmer to produce a real structured document without extensive knowledge of the system. People who write good documentation are often non programmers - they write documentation from an end user POV for their fellow end users, and if the end users aren't programmers, the documentation person doesn't have to be either in my opinion.
Of course, you can always produce and manipulate StarOffice 6 documents from your text editor, shell or other scripts. I'm working on converting our old Tex documentation script to produce SUn XML Writer documents as we speak.
Oh yeah, and no more jumping through hoops deadling with metafont shittiness. Yay.
Its a pity the 6.0 beta crashed on the poster - personally I find its the most stable and fast StarOffice yet, and that 5.2 was flaky, especially with net installs.
Do what every good programmer does:
- Comment your code
- Write READMEs and and a few HTML documents for the benefit of other programmers
- if you want to get fancy, make the code is self-documenting with Doxygen. Again, for the benefit of other programmers
- If they really need userland documentation, suggest they hire a technical writer.
A Technical Writer is someone with a degree in English or Communications. It's not particularly cost-effective to have a programmer doing what an english or communications major can do better, and for less money. After all, for user-level documentation, the english major is going to be much better at knowing what kind of information and format is going to communicate effectively to a non-technical audience. And a technical audience can bloody well read the code.The most important thing is the thing that gets delivered to the user. Normally that is an executable and sometimes user docs. What ever generates that is next important, normally code. Next important would be design.
I can't create a good executable without good code, which can't be produced without some documentation, but to say that the docs are the most important thing is dumb. I have created very good applications without any documentation. The apps were so simple that they stay in production for 5 years+.
Joe
Joe Batt Solid Design
Use Mac OS X's TextEdit.app to generate your document in RTF, and then print preview it to generate your PDF! This is the simplest way to generate PDFs that I know of.
I have a website. It's about Macs.
Programmers are notoriously bad at writing documentation...that task should be left to technical writers.
Absurdity: A statement or belief manifestly inconsistent with one's own opinion. -- Ambrose Bierce
Since it seems we have two conversations going I thought I would interject with a form of documentation. In Code Complete Steven McConnell talks about the PDL or Programming Description Language. Basically its starts out as documentation but you keep refining each piece till you get to the point the easiest way to describe a function is through code. I now use PDL when Im coding prefacing everything with 'PDL- its an easy way to lift all the description out of the code later and gives anybody behind a good grounding in what my code is doing. Quite frankly I hate trying to make my way through someone else's code, its not fun. Had to once look through an Access-based program using Macros and modules developed by a brokerage. A book-think worth of code MAYBE a page worth of comments, DROVE ME INSANE! Oh well, PDL good stuff look into it, you will remember what you wrote and everyone around you will thank you for helping them understand.
A javadoc type of source code parser that produces html or LaTex or just about whatever you want (with the proper configuration files) formatted documents.
I have been using this with great sucess at work, and it is free & runs under Linux or Cygwin. With a bit of scripting and some comment disapline, inline comments become good documentation.
"MS Word is about the worst tool around for writers."
"The problem is that it forces, FORCES, you to deal with presentation issues at all times."
I sharply beg to differ.
Naturally, you want to compose the structure and content of your document first, and worry about presentation later. I can hardly imagine any sensible writer doing otherwise. In Word, this is trivially easy.
The key is to write your document in Outline View. For all of its warts, Word has the best outline editor I've ever used. Use the outline view to create your sections and subsections; fill in body text blocks; and rearrange to your heart's content. Use change bars to track your changes if that's important to you.
Once the content is in place, note that the different levels of headers are associated with styles -- very convenient! All you have to do is define your styles, and *poof!* the presentation aspect of your document is done. Better yet, define your styles ahead of time and save them in a temlpate. Note also that your table of contents is trivially generated from your outline headers.
If you don't want to be annoyed by the instant spelling and grammar checkers, just turn them off. I do.
While I detest the anticompetitive business practices of MS as much as the next mustelid, I have yet to encounter a better application for most writing tasks than MS Word. It's not perfect, but it's better than the competition. Its cross-referencing capabilities are a bit weak for academic or scientific publishing, but for general technical writing it is excellent.
I've written a book, and several editions of a good-sized manual in LaTeX, and migrated that manual over to DocBook/SGML, and have found that working with DocBook is *much* better.
There are the initial learning curve issues, and you've got to find a writing tool that you like to use (I personally swear by Emacs' psgml-mode, but that's just me), but it is *so* much better than writing LaTeX.
Now don't get me wrong -- I've used LaTeX to typeset some *beautiful* output; it's great at that. However, in an environment where you can live with output that's 80% as good as LaTeX (with the lack of flexibility that missing 20% implies) and you want to do it in 10% of the time it takes to get the LaTeX "just right", something like DocBook just can't be beat...
Check out SmartDoc, which processes XML-base document and convert to HTML3, HTML4, LaTex2e, plain text, and JavaHelp. It is a command line program written in Java. There are also support programs such as converter to man, MagicPoint, and so on. http://www.asahi-net.or.jp/~dp8t-asm/java/tools/Sm artDoc/
I've used Word for a few years now and I've never had stability problems (although I nearly choked when you mentioned MS Word and HTML in the same sentence). Nor have I had any problems with OpenOffice 6.x, which I've been using for over a month now. OpenOffice is my recomendation for you, especially if you have legacy Word documents. I haven't run into problems with any of the MS Office formats in OpenOffice yet. It does like to warn me whenever I save to one, but so far it's been all bark and no bite. And, of course, it's available on multiple platforms.
Under capitalism man exploits man. Under communism it's the other way around.
I wrote a publication (16 pages, IEEE format) for Word and it was a REAL pain. Word stored the whole document in memory, which actually meant that part of it was cached to hard drive. I work in the Field of Computer Vision, so I necessarily had about 10 megs of images in there. Occasionally, that would be too much for the operating system, and I'd have to wait 15 minutes or so for the memory manager to catch and resolve some thrashing issues.
Also, every time I changed anything at all, Word would move around the pictures and mess everything up - even though I had all the pictures positioned as "absolute." At the end of the publication, any 3 minute change at the beginning of the document took half an hour to fix.
For the next publication, I did everything in Latex. The added bonus there was that format is separate from content, and the format descriptors where already written by IEEE (and by my school for my thesis).
Mod me down and I will become more powerful than you can possibly imagine!
http://www.e-press.com
Can Export to many file types including PDF
-
Insert sig here (slashdot) Insert cig here (Lewinsky)
- "History shows again and again how nature points out the folly of men" -- Blue Oyster Cult, 'Godzilla'
And, yes, I know that a flame could argue that many other commercially sold Microsoft products could be called "unsupported tools," so let's try to steer any jokes onto a different track...
"Prepare for the worst - hope for the best."
We've used autoduck for a while, it's pretty useful for generating a wide range of stuff iff you want to learn its nasty syntax. It's a freeware package, sources included. Windows focus.
I am sorry, but does anyone really uses MS Word for writing documentation? Why? Probably it is also possible to write documentation in GIMP or 3D Studio/Blender, but what for?
There is Doxygen - perfect tool for documenting source (that graphs!!!). There is LyX for writing nice looking text (yes, I don't know LaTeX). And there is vim (and many other editors) for writing simple text. So why MS Word????
I can't believe no one has mentioned Structured Text yet. It's really simple (you only have to learn a few simple rules of editing plain text ASCII files to express structure) and pretty intuitive (it's like Python in the sense that your indentation expresses your structure). You can convert it to decent looking html with existing scripts (that come with zope). You can convert this generated html into .pdf automatically using the GPL htmldoc program . And the Zope book was written in Structured Text, to prove that it scales.
Don
- First off, it's fully compliant SGML or XML, whichever flavour you prefer. DocBook documents are stored as nice plain ASCII which can be processed with any SGML/XML tool you happen to have lying around.
- Output options are virtually unlimited. IIRC, HTML, man, texinfo, plain text, (La)TeX and anything else you care to mention are available as output formats, with XSL providing a way to produce your own custom output.
- The Crunch: Text is marked-up for what it is, not what it's meant to look like, so you needn't know a single thing about formatting while writing content and vice versa. You know the advantages of using CSS instead of hard-coding HTML. Well, they count for DocBook too.
- Nifty features like creating tables of contents from the source and all that sort of thing that you thought only TeX could do.
- I suppose I should mention that it's extensible, hence the XML version.
--PhilRodKDE Documentation Team: http://i18n.kde.org/doc
Uh, no.
METAFONT is pretty much integrated into TeX if you're using... well, I've only used teTeX and MiKTeX, but there are scripts to autogenerate any fonts that are needed.
And... well, you can't compete with the userbase. It's been a standard for nearly twenty years. The original program is probably as close to bug-free as any large piece of software can possibly be. Did I mention the enormous userbase?
TeX is far from dead. It's Knuth's dream that a TeX file written today will be compilable and readable in a hundred years. Given how entrenched the system is, I think this is quite likely.
-grendel drago
Laws do not persuade just because they threaten. --Seneca
Off course, javadoc, doxygen and such are required for inline comments within the code. But if you want to document the design at a high level and think about a word processor, and cost is not an issue, Framemaker is it.
:))
Framemaker is the best word processor out there, far ahead of the others (at least, Word and WordPerfect). You can manipulate the document from command line, you can edit its mif version with an ascii editor, can generate xml, html, pdf, etc... This is a great tool for team work. In one of my previous project, each team (13) wrote a chapter (1 file per chapter). At build time, the makefile would extract all chapters, build the doc using framemaker command line tools (setup the version, pages, etc..) and update the website containing the documentation and the software automatically. Instruction to build the project: type "make" and all can be found on the website (assuming of course no compile error occured, which never happened.
Sadly, it is soo expensive that I do not use it since I left Nortel. I wish it would be open source...
Note, I never used Latex and Texinfo, so I am missing some experience with non WYSIWYG tools.
Remember the year 2000? They promised us flying cars. They delivered the PT Cruiser...
This is true, and the way the world works. Since you can't change it, it therefore makes sense to adapt your development process to it. Don't write "temporary" code. By all means prototype, but always write to production standard. No lazy organisation, crappy identifiers or forgotten error checking should be allowed, as a matter of good practice.
If you're going to leave an area of code unfinished for more than a few minutes, it's also smart to include some sort of marker message that comes up every compile/run to warn about this. That way, no code that's not up to standard ever goes unreported.
If you disagree, post your argument. (-1, Overrated) isn't your personal censorship tool for views you don't like.
Source is simple ascii!
Easy to produce, professional-looking PDF and HTML.
That seems to meet all your requirements!
On a redhat based distro, do
rpm -ql sgml-tools | grep guide
to get started.
Excellent dvi-> pdf convertor
Is anyone using SDF (Simple Document Format)? I ran across it at http://www.mincom.com/mtr/sdf - the last update was at 25-May-99, so I don't think it's being actively maintained anymore (unless it's being maintained elsewhere).
I like many word processors, most of all Word which was the best thing Microsoft ever wrote. Now I use abiword where I can, and try not to use any pictures ;-)
/* FunctionDoes: blah bah */ style of comment in, or whatever your regular commenting style, then write a perl script to convert them all to HTML. It knows your function names, it can find out the arguments, and it takes about 30 lines of code.
But for documentation, nothing beats writing perl scripts. In my last job, I had to write a big-ass test script, and not only did I have perl to generate the code for me, but to generate comments, and HTML documentation too.
Simply, just put a
Beats re-typing it any day.
There are two major problems with storing binary formats in repositories: diff'ing and merging. If you want to establish the differences between two versions, you are reliant on the tool that created the document to do this for you. (MS Word does, of course, but this is a problem in general.) Further, if you want to allow multiple people to edit at the same time, you can do it and merge semi-intelligently with text-based formats. I don't know of any word processor with a binary format where I can be editing chapter 1 of our main design document, my colleague can simultaneously edit chapter 3, and we can get all the changes back in with no more than a check to resolve any conflicts.
If you disagree, post your argument. (-1, Overrated) isn't your personal censorship tool for views you don't like.
In my opinion, DocBook (http://www.docbook.org) would offer you the mose flexibility in terms of document content and output options. What might work even better for you would be to have your own format, possibly your own XML DTD, that you'd edit the source in, and then process it (via XSLT in the case of your own XML DTD) to get docbook formatted XML. At that point you'd be able to produce any kind of output you'd like (print, web, online help).
Use LaTeX, not TeX. ascii, processed a million different ways...to pdf, ps, html, etc.
for LaTeX to html, the best I've used so far is htlatex/httex the link is on the www.tug.org page somewhere.
apache cocoon is an awesome publishing tool. I recently created a site that creates a web site and a series of PDF documents from the same source. Your input documents are as simple as you want them to be, because you define it yourself and transform it into HTML or XSL:FO via XSLT.
std::disclaimer<std::legalese> sig=new std::disclaimer; sig->dump(); delete sig;
The obvious answer is to write the (at least the skeleton of) the docs FIRST. Then your work is easy.
I have written a Python utility for converting "smart ASCII" to HTML (and another one for XML). I plan to adapt this to LaTex, but it hasn't happened just yet. The format I call "smart ASCII" is probably even simpler than that used by aft, but the idea is the same. Basically, just use the same simple conventions you would in writing email or a newsgroup post.
. tx t
I've written about this utility in several IBM developerWorks articles (most using it just as a touchstone). Probably the best starting place is:
http://gnosis.cx/publish/programming/txt2dw_tip
Links to related articles (and to the source) can be followed from there.
Buy Text Processing in Python
You hate it because you are doing it at the wrong time. Write your documentation before you write one line of code. Then proceed to write your code to implement the documented features, instead of later trying to document poorly documented source code. ;)
Viola. Cello. Whatever.
Edith Keeler Must Die
Of course it also does more, but the only way to get the skinny is to visit it's homepage at: http://www.mincom.com/mtr/sdf/
Enjoy! -- Tails
--
I used to work at a small-town newspaper - we gave all the reporters old macs with nothing but simpletext and excaliber (drag&drop spellcheck, usually comes bundled with the mac version of latex). Reporters had to actually concentrate on content not layout. Once written, a story was kicked to a single layout person who pasted the whole lot into quark & fussed about with presentation. Jacked our production rate *way* up from an earlier system involving reporters prettyifying their work in word before layout people had to strip it all back out before pasteup..
Are you writing design documentation? Or product documentation? i.e., are you writing for programmers or users?
Programmers almost never should write documentation for users, if that's what you're talking about. Docbook, YODL, AutoGen PodPeople MagicDoc... none are appropriate documentation methods for users.
Design documentation, however, is different.
Potato chips are a by-yourself food.
If you're stuck using Word (as I am, because of work stipulations), try using its more advanced features. Read the Help files on Styles. This will keep a lot organized and make the program ship-shape itself a bit better.
*SHHESH* !!!!
.sig was right: "Putting a lameness filter on Slashdot is like putting a shit filter on your ass!!!"
FINALLY, a post which really talks to the question this thread was started for!!!
Damn that
We _all_ have to, at one time or another, create documentation for something. I have to create documents for the Luddite users on my network so they know how to keep their trousers from becoming unzipped in front of their customers...
I have used Word on a great many of these documentation projects, great *and* small. It has always performed fine for me. There are a crapload of features I'm sure I could be taking advantage of to make my documentation even snazzier but I'm too lazy to really LEARN Word. Like as not I've been holding out for an Open Source alternative like Star Office or something to step up to the plate...and the latest version really holds up well. Compatibility with MS-Office's formats helps a great deal with the transition and it is available for Windows AND *n*X.
For exeptionally large jobs, I would recommend an actual professional layout package like PageMaker/FrameMaker on the closed source OS's. For simplicity's sake, TeX and LaTeX for simple ASCII-text-with-markup in them.
Your subject and your audience really dictate the format and platform of your documentation. A new version of Apache doesn't come with a README in Word/RTF format but your latest FPS game will.
-PONA-
King of the Who?.sig
+that's funny...I don't FEEL tardy.+
Of course you should be using Javadoc which automatically formats linked HTML pages for documentation. The Java runtime specification book was actually a Javadoc from the code. So the system can do more complex formats.
Of course that pre-supposes your using Java, or maybe a reason for using it.
IMHO this is the best way to go. You can use Perl with Win32::OLE to generate your word files, adding in all the pretty formatting, especially if you ever need to automate any of it.
-jc
Use an outliner. There are several out there, the one that springs to my mind immediatley is Omni Outline (www.omnigroup.com).
Using an outliner allows great hierarchical structure allowing you to edit quickly.
A good outliner will also output to HTML/XML where you can apply a CSS file for both screen/print mediums. Mozilla, even IE 5+ will ensure your docs appear how you want. Heck, you can change the CSS file and not worry about the presentation at all. Just create a few CSS templates and off you go.
I don't know why you'd make it harder than you have to.
I manage Technical Publications for small platform-agnostic music/audio SW technology company known for a browesr plug-in, but also established in the mobile world. My group does all the documents that the outside world (licensees, end users) see describing our products and how to use them:
All these document types (and more, actually) can be delivered in plain HTML, HTML with a JavaScript viewer system, PDF, and we can even go to film for old-fashioned printing. (You, as in 'on paper, from a printing press'?) The output not only looks great, and conforms to the company's overall style/graphic identuty, it even looks consistent in all the output formats.
How do we do this? We build all our documents in FrameMaker, which does all the output except the HTML, which is done in the companion product WebWorks Publisher (WWP) from Quadralay. (Yes, I'm a Dmitry booster, and I do suffer from Adobe-user guilt in this regard, however my feelings are deeply mixed since as a denizen of the tech pubs ghetto I find FrameMaker is a solace to my otherwise tool-impoverished people...)
But it's not just the products you use -- your practices matter at least as much. Just as in good program design, good document design is matter of deciding on a set of elements and then using just the elements -- no jerry-rigging, no kludges -- to build the whole. With FrameMaker, the elements come from a template containing Paragraph and Character formats. In WWP you create a corresponding template with the HTML tags you want for the corresponding Para and Char formats, designed to reproduce (perhaps with the help of CSS style sheets) the look of the FrameMaker formats. Once you take into account all the included illustration and book part files, every document is a lot like a SW project with lots of hieracrchically dependent parts that all need to synchronize. Think of the output formats as 'build targets. ' Just like with coding, if you follow your own rules it all works out quite nicely.
Is this a lot of work to set up the first time? Yes indeed, but this is how the big kids do it.
Could a coder use FrameMaker to do documentation? Possibly, if it were the right person, though this would be more likely to work well if a tech pubs person were to set the templates up for the coder. However with FrameMaker at $800 a seat this approach is probably too spendy for most sizeable shops. This system works better with a smaller number of dedicated tech pubs people serving a larger number of coders.
Is there an easier way to automatically produce the same level of quality across a similar range of output formats? Not that you can achieve without tripling your tech pubs staff and tools budget.
Can you automatically turn a .h file into an API Reference? Depends how good you are with Perl. I have a tool of my own that turns a .h file into a formatted, cross-referenced, TOC'd FrameMaker file, but it doesn't pull source code comments into the FrameMaker document. Not because it couldn't -- it could, if that's what you want to do -- but because frankly in my experience most of that stuff needs to be so totally restructuired and rewritten anyway that it's almost always easier to just read the function signature and start writing. (With the source open in a separate editor window, of course.)
(Sometimes we rewrite source code comments too, but since we aren't publishing the source code in multiple formats, that just happens in BBEdit or CodeWarrior.)
Which brings me to a secondary comment on the article title "Developers: Writing Documentation" -- While I agree that all developers should certainly document their work, I wouldn't necessarily agree that what they write should automatically be used as the product documentation that the outside world is given. Because the talent of being able to communicate about technology is not the same talent as being able to create technology. It seems a comparatively small fraction of people get to have both talents. (And of those, a comparatively small fraction will admit they can do the one they enjoy less!)
What was hard was getting it set up, and getting help out of the DocBook people in the know. (They can be pretty unapproachable sometimes.)
What was also hard was getting print output to work nicely. I was running fine for a while until I upgraded openjade, and then blammo--two-sided print output doesn't work anymore. Openjade simply refused to put the two-side directive in the TeX output, so I did it myself.
And what is it about my document that causes openjade to take 3 minutes to pump out TeX output, when it does the HTML in about 5 seconds?
Why is it that when I put two tables on the same page openjade/jadetex doesn't take that into account and keeps printing text off the bottom of the sheet?
The other place I've looked is Xerces/Xalan/Fop at Apache. I like the Formatted Objects idea, and it seems pretty sound. Also, the whole thing was about 827 times easier to set up than the jade stuff. Unfortunately, the code is alpha and doesn't work very well, sometimes crashing during the render.
"How does ORA do it, then?" I hear you asking. They have custom in-house tools for processing DocBook that have been in development for some time. Word on the street is that they might be releasing them soon.
Conclusion: if you want print output, you might have trouble getting what you want with DocBook at this time. At least when I code TeX it does what I say. (I don't recomment plain TeX for documentation. Maybe LaTeX since it's easier to convert to HTML. And pdf(la)tex produces nice PDFs.)
I'd go for LaTeX. Granted you have to get a little used to it. But I found that I could be more productive using emacs/latex/xdvi as an acceptable documentation generation toolset as I could be if I were lashed to a chair and forced to use some Windows word processor.
Years ago, back when I could recite pages from the VMS docset and could make my own grant bus cards, we used VAX DOCUMENT for documentation. As it I discovered one night, it was nothing more than an SGML (or SGML-like) front-end to TeX. We used it for project documentation sometimes cranking out manuals of several hundred pages. While I'm sure that some DOS/Windows WYSIWYG word processor might have done the job, it would (I'm positive) have been much, much more painful.
Sadly, the choice of tool that you use might depend on how long this documentation has to live. If you ever leave, will your employer know to look for a candidate that has experience in whatever tools you decide to use. It's unfortunate but your boss might force you to ``dumb it down''. Of course, we can all smile to ourselves over all those corporate documents that won't be readable in a few years when Microsoft decides to change the .doc format again. Happily, I have TeX/LaTeX files that are over ten years old that are still useful so you might point that out to your boss if s/he decides that you should go the MS route.
CUR ALLOC 20195.....5804M
You might want to check out the PostNuke Documentation Project. We are creating content dynamically using a modularized version of PHPWiki. In a few days we should have the ability to output to a print-friendly format or to .pdf (with our new top-secret pdf module) via the regular avenues of content management within PostNuke.
Of course it is all still under development and a lot of the new features will not be available until we release the new documentation site on Monday, but it will be worth the wait.
The real plan is to customize a postnuke release specifically for documentation projects.
--Grape
PostNuke Documentation
http://www.support.postnuke.com
--grape --PostNuke Documentation
I use Word almost every day, and while many of your comments are true for default behavior, you clearly have not attempted to actually learn the program. To take the issues in the order you cite them:
/. post would be...
1. Word actually doesn't force you to deal with presentation issues at all times. Are you familiar with outline mode? I usually do my first drafts in outline mode, which allows you to focus entirely on content and structure independent of formatting. Outline mode works with styles to specify formatting globally for a given level in the outline. So if the top level in your outline applies to chapters, you can easily define a chapter heading style that will be automatically applied to all the top-level items. It really works well.
2. It's been said already, but it's worth repeating: Real-time spelling and grammar correction are really easy to turn off. Really easy.
3. Lists & indentations. You should learn how to use styles. This is exactly what they are for. For example, my default template has a "bullet list" style. If I want something to be a bullet list, I apply this style to it. The "tags" aren't visible, but they effectively are there. If I ever decide that a bullet list needs to be indented differently, or have square instead of round bullets, I can make the change once for the style. Once you've set up your default doc template with a reasonable set of styles, you never have to worry about presentation during early stages.
4. I don't understand what you say about tables.
5. "Word documents seem to be written to Jr. High level at most"? What the hell? This is broad generalization at it's worst. I bet more doctoral dissertations are written in Word than anything else. Although I did get a good laugh thinking about what the average grade level of a
Now, I'm not saying Word is the end-all be-all. I'm just saying that you're an idiot because of the 10000 things wrong with it, you've picked issues that are almost univerally untrue, and simply reflect that you haven't learned to use it.
It can be reasonable to use version control with binary files.
I believe what you mean to say is
"is it reasonable to use version control when you give up the following benefits:
1) compact storage by using deltas
2) easy 'diff'-type comparison between versions
3) machine assistance in merging branches."
(1) these days is hardly noticeable.
(2) and (3) are, admittedly, the big problems.
The primary function of version control is to maintain a snapshot of files at multiple checkpoints. There doesn't have to be parseable data to do that.
Thank you; that's what I meant. I regularly stick binaries away in VSS. I just don't expect it to do anything fancy with the binary for me.
Please mod this post only if you think others should/n't read this. I have enough ego^H^H^Hkarma. Thanks!
Adobe Distiller has the ability to mascarade as a Printer driver, which means you can type up the text in any gosh-darned format in any golly-gee editors, then use the Distiller driver to export it to a file. Don't know if this will help, though there seem to be a lot of suggestions here and I'm sure one will work.
From the website:
Also, you can export your TeXmacs files to LaTeX which gives you access to a wide range of document translation programs. Check it out.
I use and like Simple Document format. It uses a fairly
simple text based format, is extendable using perl, and
can produce documents in a variety of formats, including
HTML, SGML, Docboox, HTML, RTF, PS, PDF, etc...
http://www.mincom.com/mtr/sdf/
I also prefer GNU texinfo and have used it to easily build 100+ page manuals, with tutorials etc. texinfo is a simple ascii-based markup language. From a single .texi file you can easily generate .html, .ps, .pdf, and .info. The manuals don't look as professional as ones that have been typeset in quark, but texinfo has the highest quality to effort ratio of any documentation system I've seen to date, including word, tex, latex, docbook, quark, etc. Its biggest limitation is that I would also like to generate troff-style man pages but texinfo doesn't support that.
The word 'Documentation' as used in software engineering, is often used to characterize a number of different documents. Here are the different kind of documents I produce in my position as a lead tech in a software company:
1. Interface/API documentation: Here I normally generate latex from the C++/Java/C sources with DOC++ and publish it as PDF's. I could generate HTML but most of my collegues agree with me that printed documentation are nicer.
2. User Manuals: It varies. troff for man pages, Latex for hardcopies, M$ Word if nontechs has to edit/localize the stuff.
3. Tech Specifications, Software Design Documents: Such documents are mostly used within the company by the tech staff, so I use Latex for formatting and M$ Visio (and sometimes some fourth-generation tools such as Erwin or Rational Rose) for diagrams. It works for me! And these can be put under source control (we use CVS).
4. Collaborative documents: Such as proposals, RFPs, Site Acceptence Test documents that non-techies (Account and Project managers most of the time) has to edit.. For these I use M$ Word/Excel and I must admit I use a considerable amount of time on the things that LaTeX does automaticially for me - that is layout and presentation.
As a rule of thumb I always submit documents as PDFs. Good luck and always remember YMMV!!
texinfo is better than latex for documentation, both in final output quality, in number of output formats supported, and quality to effort ratio. I used to use latex for documentation but have completely switched to texinfo.
Not arguing in favor of MS Word (far from it), but if you'd used a Master Document and SubDocs to split up your information, then you might have avoided some of this thrashing problem. Or not, but I'd be careful in damning a tool until I was intimately conversant with its many functions, and the modern word processor has a lot of options and capabilities.... ones most of us never see/use/learn.
-- Mal: "Well they tell you: never hit a man with a closed fist. But it is, on occasion, hilarious."
Texinfo is strictly superior to TeX for software documentation. See above.
Excellent! I'd love to be able to generate PDF and PS from the exact same DVI source file; this looks like just the thing.
Dude. You're supposed to write the documentation first.
Yes, the idea with literate programming is that the documentation and code is all one file. It prevents the whole "Oh, now I need to do the docs." problem, and the problem where the documentation diverges from the actual code. If you change the code, you change the documentation right in the same file next to the code. I find noweb to be an interesting tool. It is Latex and Lyx aware. The one page document on noweb below is very informative: Onepage guide to noweb
You forgot one: Oft times, vcs will store binary versions as complete objects (rather than the forward or reverse deltas used with ascii text files like code). This means if I check in 16 versions of MyDoc.doc, then I eat up a heck of a lot of space. Space always seems to be a consideration on version control systems, so this is a good reason to use ascii-based doc formats.
-- Mal: "Well they tell you: never hit a man with a closed fist. But it is, on occasion, hilarious."
First, turn off Auto* features and Agents. Switch to Outline Mode. Bang out your content in the hierachy you want. Set up your styles. Apply your styles to the sections that need them. Insert generated blocks like TOC and index. Done. Go buy a book on Word, it's a better app than you think.
I know this is redundant, but LaTeX is probably your answer. I've used docbook as well, but I personally prefer LaTeX. IMO, DocBook goes too far for most documents.
:)
Either is better than a proprietary format. You have to think in terms of Longevity, and Word is definately bad because it is incompatible from one version to another. Of course, it's a screwed up program as well too (and that is not a hack against MS, it's a hack against Word itself; ther MS issues are something entirely different that could take all day as well.
At work I'm forced to write in VB. I'm trying to find a (hopefully Open Source) solution to generate documentation from in code documentation that I don't have to spend months teaching everyone how to use. It would preferably integrate with VSS as well (I'm also working on converting us to CVS ;).
I could write something, but I'd rather not replicate previous work. Any suggestions?
If you do not need true typesetting, don't use TeX or LaTeX.
TeX is basically unusable outside of linux/unix shops/institutions because very little windows users posses unix tools.
Word should be ok.
The main thing you need to remember is that word will journal your changes to the end of the document. After many many changes you need to save the document in a new file (file->save as) to force word to save it after all journal entries have been applied.
I've seen an autocad book document for several chapters with many pictures go from 50mb to 10mb after doing a file save as.
If not using it for typset documents, use a word processor.
If you need typesetting use a typesetting program.
Many books have recently been written in Word with the typeset type diagrams done in a different tool then brought into word as bitmaps.
SDF is the "Simple Document Format". Unlike DocBook, SDF has very little markup and is able to produce HTML, PDF, PS and other formats. The only drawback is that is seems kind of "dead". The latest version dates from a while ago.
SDF Page: http://203.101.254.79/mtr/sdf
Even with keyword expansion and line-ending conversion disabled? I added my Word.doc files like this:
cvs add -kb word.doc
This seems to work for me. Is it not working for others?
If you're going to write documentation in PDF, I might suggest checking out Adobe InDesign 2.0 when it ships (which should be shortly, according to what some Adobe folks said at the recent Macworld.) You can use XML to build the docs structurally, then you can use InDesign to map those structures to text styles.
I'm a bit of a font geek, and one of the things I've always hated about printed app documentation is that so much paper is wasted on bad layout and typography. The great thing about InDesign is its support for OpenType fonts, whose professional typography features like small caps, ligatures and oldstyle figures make text easier to read. InDesign automates all of these features, so all you have to do is define the styles in terms of their XML/XHTML counterparts.
I realize some Slashdotters have been led to believe that Adobe is responsible for Sklyarov's recent ordeal and will thus not bother considering this as a solution, not to mention it doesn't run on Linux, but you should keep it in mind as an answer to both the structural and aesthetic aspects of software documentation. InDesign 2.0 in combination with one or more OpenType Fonts can churn out truly beautiful documents.
My second choice would be LaTeX through the LyX front-end. You still can't beat its bang/buck ratio, and it's really still the best way to do layout in Linux. If you're sick of the standard TeX fonts, though, you should check out the book TeX Unbound by Alan Hoenig.
Ralf
The trouble with the world is that the stupid are cocksure and the intelligent are full of doubt.
-Bertrand Russel
After loving MS Office (even though I freaking hate MS) I discovered OpenOffice and I have totally mastered it. I have to say, OpenOffice gives me much more control over my documents and it is cross platform. Not to mention an open file format and Basic, Java, and other API's.
You might give it a try, I use it exclusively for all my programming design/documentation these days. I have a whole library of document, drawing, and spreadsheet templates I've created.
Forgive my ignorance, but what's wrong with ps2pdf? Is it only the lack of TOC, x-refs, URLs? (I hate that stuff anyway...)
The combination of Miktex (LaTex for windows) and Winedt is pretty awesome. Unfortunately Winedt isn't available for Linux. pstricks is also pretty handy.
For the acronym challenged, POS means "piece of shit". Think cow excrement. The phrase means "having no value".
For an example of the proper use of this acronym, see the parent post.
For technical papers, I still use troff with the mm macros. I can incorporate figures either using xfig(1) or raw PostScript.
Both cases above are:
If you reply, do so only to what I explicitly wrote. If I didn't write it, don't assume or infer it.
Abiword saves in lots of formats, including LaTeX, HTML, XHTML, MSWord, rtf, KWord, plain text, and gzipped abiword format.
;o)
From LaTeX you can make PostScript (`latex filename.tex && dvips -t letter filename.dvi -o filename.ps`) for quality printing or Adobe PDF (`pdflatex filename.tex`) as well as HTML, rtf, plain text, etc...
But that's beside the point. If you write the docs in plain text you can very easily convert them into various format if you stick with the right tools
My 2 cents
It's funny you mention FrameMaker. I used FrameMaker for long documents. FrameMaker was one of the apps that compelled me to consider using exclusively free software.
Towards the end of my FrameMaker days FrameMaker became Adobe's app. I interpreted Adobe's lack of development of FrameMaker as Adobe's disinterest in the software (and perhaps more generally their disinterest in publishing software). Others had noticed FrameMaker's lack of continued development too and some users formed a mailing list (the "framers" list, if I recall correctly) to put together a petition to get Adobe to improve FrameMaker. You see, FrameMaker had large blocks of functionality (I'm convinced) purposefully left unimplemented or under-implemented so the third-party market would develop extensions for FrameMaker. Unfortunately that market never really took off and what existed wasn't that much compared to Photoshop.
As time went on, I discovered more and more bugs in FrameMaker and I grew increasingly frustrated because Adobe wasn't fixing the app and I could not fix the software I had invested so much time in. On the other hand, I had developed a significant body of documents in FrameMaker. I needed to change to something I could get my work done with and improve as I needed.
About this same time my work lost some employees and my responsibilities shifted to doing other things. Documentation writing had to be put on the back burner. I saved all my documents in FrameMaker's textual markup format (in the hopes of being able to not lose all my work to some non-portable binary format) and put the entire documentation software issue aside.
The question of this thread intrigued me because almost a year ago my work hired some more employees and I forsee my responsibilities shifting back to documentation writing; I'll be in a similar situation to the reviewer--evaluating documentation software. But this time around I'll know I don't want to be stuck with a tool I can't fix. I don't know what software to pick just yet, but I know proprietary software (including FrameMaker) is not up for consideration. I want to use something I can move away from if something profoundly better comes along (or if something profoundly bad happens to the software I choose).
My tip to other documentation authors: consider where your work will be in a year or two (long enough where you will have made a lot of documents, short enough where you can guess what your documentation needs will go); consider what those needs might require of the tools you choose today.
If you really want to use anything non-trivail latex, my advice: buy a book. I don't know them all, but I like "A guide to Latex" (Helmut Kopka & Patrick W. Daly).
(X)Emacs has a great LaTeX mode. The referencing mode LaTexRef is really cool.
Why has no one mentioned texinfo? I know it used tex on the backend, but it provides a much cleaner set of macros to work with, and produces some damn fine HTML and PDF's.
Ever thought man pages were limited in that you couldn't automatically go to a referenced manpage? Use info, hit tab until you reach the reference, then hit enter. Walla!
Yes, info has become my all-time favorite. Far beyond the limited HTML markup. Not convinced? I would like to bring to your attention a few posts already made concerning info(1) and the document format texinfo: 2818653 and 2819778
I've recently started the chore of changing an existing TeX document into texinfo format. I would have loved to use a converter or a formatter from TeX to texinfo, but alas, such a tool was not available. vim's search and replacement works pretty well. Regardless, since texinfo docs can create TeX, XML, and HTML documents, I believe it's the best of the docformat-to-docformat wars. Additionally, it's a pretty simple markup to use.
Check out info2www by Roar Smith for a simple way to push out your installed info docs.
Here's the GNU Texinfo documentation.
The only other acceptable format, IMHO, would be docbook.
assert(expired(knowledge));
Well, after some research, I settled on using LaTeX. Actually, I used the MiKTeX distribution on MS Win NT4.0. For the screenshots and Visio diagram manipulation, I wrote some Perl scripts and used ImageMagick and a copy of GhostScript 7.0 for producing PostScript and then PDF files for printing and distribution purposes. The comp.text.tex was a valuable resource as well.
I spent one weekend at home learning the basics of LaTeX, used the "Article" class to help produce a good document layout. Over the next 4 months I learned to write my own macros, create table of contents, indices, glossary, etc, and came up with a 500+ page technical design manual.
Not once did the system crash on me, and I could spend most of my time on the content. Yes, I did spend time on converting Windows .bmp bitmap files into JPG format for inclusion into the document, but with the help of some home-made Perl scripts, I pretty much automated the process of conversion, cropping and resizing. In the end, I preferred this method to dragging and resizing bitmaps within MSWord.
Customized Perl scripts were written to dynamically create LaTeX tables which showed software versions used in our product, references to other documents, etc. The entire document was dynamically "built" into a PDF file.
It took a little time to install, figure out and customize.
The end result was a very clean, compressed PDF document, which we could distribute to all interested parties via email.
I really learned a lot, and it saved me a lot of time formatting the document; I had content, and I had software that did the formatting for me.
Everyone was impressed, but LaTeX was not the "standard" within the company. "We must use MS Word", I was told. This came straight from upper management. Much of the document generation was automated, and there was obvious benefits (free open-source software, no crashing, PDF output without the use of Acrobat, dynamic image manipulation and data inclusion, etc). Even so, MS Word was to be used in subsequent documents.
The point is, even though you might think MS Word is crap and you want to look for alternatives, bear in mind the standards used within the company. Standards become even more important within "global" companies; too many non-standardized products can be costly.
Also, let's say you write a document in LaTeX or DOCBOOK, you quit or get hit by the bus one day (heaven forbid). How are your co-workers going to maintain your document? Can the secretary easily make formatting changes? How about your boss?
Over the past few months I began to use Word for much smaller documentation. It's a pain to use, but I did learn how to use it to make decent looking documents. It just takes more time to produce a document in Word than it does in LaTeX.
Hope this helps in giving you some ideas.
After many months of searching, I have yet to find a way to properly convert a PDF file (generated from LaTeX) to MS Word, retaining all formatting with the hyperlinks and references in MS Word format. Does anyone know?
On the whole, the cross-referencing is less useful than Exuberant-etags and id-utils under emacs, but it's still pretty cool.
Doxygen can produce TeX output, however it doesn't look great, and for a project as big as Samba it can overflow internal limits in the default build of LaTeX. I'm sure you could patch it to look better.
Another weakness is that it does not know about CVS. It's nice to see the history of the code integrated with the current state. LXR will do that for you, but at the cost of a more complicated server-side installation.
--
Martin
TeX was never meant to appeal to "Joe Average". Knuth says as much himself in the TeXbook. It's meant for producing technical manuscripts of the highest possible quality. For most tasks, MS Word will do the trick.
But for those of us who need kickass math functionality, are preparing a thesis, or are awed by the geek-factor, TeX is *it*.
TeX (and by this I mean LaTeX as well) is not meant to be used lightly. But for large, complex projects, its power and utility are evident. It simply scales much, much better than editors like Word.
Good for StarOffice if it wants to take over the office suite market. It's an important part of getting Linux on the desktop... but TeX is something utterly different.
And about the fonts... what is it you're trying to do? Do you have some TrueType fonts you want to use with TeX?
http://www.radamir.com/tex/ttf-tex.htm
It's nontrivial, but it certainly can be done...
-grendel drago
Laws do not persuade just because they threaten. --Seneca
In my company we have a large UNIX base because all the hardware designers (VHDL/Verilog) and DFT group use unix boxes (Sun/HP). FrameMaker runs on most platforms out there (sure its not free), but its flow is very easy. It has very powerful formatting options and can import PS/EPS pictures with ease. One peave that i have with it is that the diagrams are kind of a pain in the a$$. but you get used to it. It producess very good looking documents, on par with LaTeX. I used everything, from HTML, LaTeX, word, ASCII, and although LaTeX is my favorite, FrameMAker is not too far behind. In a multiplatform environment i think it is the way to go.
Just my $0.02
CWEB is a version of WEB for documenting C, C++, and Java programs. WEB was adapted to C by Silvio Levy in 1987, and since then both Knuth and Levy have revised and enhanced the system in many ways, notably to support C++ and ANSI C. Thus CWEB combines TeX with today's most widely used professional programming languages.
m l
It is available at http://www-cs-faculty.stanford.edu/~knuth/cweb.ht
I just had a look at the HTMLDOC docs (if that's not too redundant.)
This is absolutely killer. I've wanted something like this for years. HTML is not a layout format, but will do fine for most documents, but was lacking a few simple things to let it be a reasonable printable document format. HTMLDOC intelligently filters HTML into very presentable PS or PDF documents. (Look at the online docs for good examples...)
HTMLDOC adds the missing pieces! Margins, page breaks, duplexing, headers and footers, even the ability to define the order and options for each chapter in a book and be able to process them all at once.
This looks VERY good. If it works as advertised, I may be buying the supported version RSN. I'm impressed, and it takes a lot for software to impress me.
The fact that it's free and open source, too, is just icing on the cake...
"The future's good and the present is nothing to sneeze at." - Roblimo's last
I have had the same problem, I was tired of writing documentation and then trying to view or edit it on different platforms running different software. I have come to the conclusion that one of the best and cheapest things for me ( I am a student ) was to learn LaTeX and use it along with Emacs. There is a package for Emacs that makes the editing less painfull and although the learning curve might be a bit long, the results pay off. You can present everything in PS, PDF, HTML, DVI or whatever you wish format. As long as you have the .tex file on your hands you are all set. There is more to it once you manage to learn how to include graphic images and build complicated tables. I was very pleased with the results and my teachers were surprised to see something besides .doc files during the presentations. I would highly recommend the same thing for you.
Works terrific if you're documenting source.
The AbiWord wordprocessor saves its files as XML, can print to PDF files (and I think HTML too) and has never crashed on me.
Visit http://ringbreak.dnd.utwente.nl/~mrjb/growingbettersoftware to download your free copy of the book
http://www.xmlmind.com/aptconvert.html
APT = Almost Plain Text
It is a _very_ simple markup language with almost no tags as the formatting is done implicitly -- like headings start in column 0 while text start in column 2. It does the job for me. Is has the most needed features and if you need more advanced formatting you should probably consider making your document simpler :)
It uses LaTeX, ps2pdf and makes both HTML, PS and PDF output. The format is to near "text" that it is quite readable in text-format also. Oh, and it it written in JAVA.
dunkel AKA Jesper Holm OlsenGuitarist in the Commodore 64 band PRESS PLAY ON TAPE - http://www.pressplayontape.com
http://www.ntg.nl/context/
:(. Use PDF :)
Very nice, clean macro set. _Much_ better than LaTeX if you want to change the look of your documents.
Powerful toc/index capabilities. Powerfull PDF creation w. automatic linking.
You can use XML as input language.
_Very_ nice. Took me one day to learn, after that two hours to create the formatting style for writing contracts. I couldn't have done that in LaTex.
No html
Use LaTeX with emacs (or vi), then compile to pdf with pdflatex. Easy, simple and fast.
lyx sucks. It's buggy, uggly, difficult to use and certainly not WYSIWYG.
I've also written several docs using Word and then decided to switch to some reasonable doc writting software. I looked for reasonably easy to learn WYSIWYM tools, much easier than TeX if possible. I finally chose Lout, which is a small (times smaller that TeX based stuff) nice typesetter included in Debian GNU/Linux. I believe that it can be your solution also.
we just wrote a web app which uses xml/xsl processing to create web pages, so decided to write the docs in xml too. nice text based format for the doc, easily readable & updateable by us, easy to version control etc.
:)
we use xalan/xerces from xml.apache.org to transform the xml into pdf/html using xsl/fop for presenting to users etc - bit of work setting it up, but we'd done most of it already for the app so it wasn't much work, and now its set up its a lovely method, just edit the xml and run a script to output to pdf/html.
anorakgirl
ps i do think we have a habit of doing things the long way round though, sticking with text editors & scripts rather than using ready made apps...
If you want ASCII input, and somewhat fancy output, look at restructuredText (http://structuredtext.sourceforge.net/). It is proposed as documentation standard in Python. e.g.
bla bla
=======
is a title, and
- bla bla
is an item in an unnumbered list
There is no other way to put it. Docbook, in either SGML or XML variants, is the way to go. Period. It has all the elements you will ever need for software docs, your data will always be readble (sgml or xml is text), you can integrate documentation "build" in your make files, you can include or exclude content based on conditionals, the system forces you to think and structure your material sensibly.
_ markus/ indispensable.
Installing all the necessary components by hand can be a rather painful excersise for the uninitiated, though. It's usually best to install your favourite distribution's docbook package. IIRC on Debian all it took was an "apt-get install docbook", your mileage may vary elsewhere but I hear FreeBSD has everything you need, nicely packaged.
You would do well to read the "duck book" (online at http://docbook.org or available from O'Reilly). Other useful resources are the FreeBSD project's documentation primer at among other places http://www.freebsd.org/docproj/sgml.html. If you ever need to set up a windows machine for sensible doc writing, you'll find Markus Hoenicka's guide at http://ourworld.compuserve.com/homepages/hoenicka
-- That grumpy BSD guy - http://bsdly.blogspot.com/
Be wary of grandiose claims for the power of LaTeX2HTML. Yes, it usually does a good job of converting simple to moderate LaTeX documents. However, once you start writing your own style files and using complex macros, it's a whole new ballgame. Theoretically, L2H can be extended to cope with any new macro, but you need Perl skills to do so and API documentation is poor-to-non-existent. Various obscure bugs may crop up from time to time, configuration for some odd situations (such as custom style files) can be non-intuitive, it's been in beta for years and releases are infrequent (although I notice that a new release came out in December).
It's not a bad program, but YMMV for actual use. (Note: I make my comments after writing a 100 page product manual in LaTeX.) OTOH, I must admit that a printed LaTeX document is a thing of beauty. If you're serious about using it, you definitely need to buy a book or two (say Lamport's and one more comprehensive reference).
If you're starting from scratch though, maybe you should give DocBook a proper go, given that it is supposed to be the format of the future and subsume all others.
Cheers,
Ade_
/
Big Bubbles (no troubles) - what sucks, who sucks and you suck
Unless you use pstricks or similar packages.
What is wrong with ps2pdf ? It produces PDF files as good as the ones produced by pdflatex/dvipdfm (assuming you set up dvips to use type1 fonts).
OK, I accept the need for fixed interfaces between different modules or programming teams to be documented. However, I would suggest that it's easier to spec the interface directly in the language you're using, via an interface class in an OO language, for example. This avoids any chance for misunderstandings between teams, as the language will typically enforce that interface. If you need "low level" documentation, just add comments as necessary to the interface spec. There is no need to duplicate this effort by copying everything into a design doc as well; just print the source code to your interface declaration.
If you disagree, post your argument. (-1, Overrated) isn't your personal censorship tool for views you don't like.
we've used a custom solution to create user
documentation. Our markup is very simple and
very generic (no format-specific information like
font sizes or specific styles, etc.). This allows
us to target multiple targets that we can use
for our final document. Right now, we're targeting HTML, but we have done MIF and some
limited RTF (and could do other markups, including
XML variants, tex, troff, etc. if necessary).
The nice thing about a custom solution is that you
can tailor it to your needs. Our docs are structured
in a hierarchical man-page style tree, so we've developed a shorthand that allows easy
specification of links to other man pages.
One big advantage of a text-based markup is that
it is very easy (and quick) to make a change,
commit it to the CVS tree and regenerate the
target document. (I used FrameMaker several
years ago, and generating HTML output was a
painful process.
And of course, a text markup generally produces
smaller document sets (unless you include a lot of
images).
Another thing that we've done is to automatically
generate things like index pages (per section)
and a permuted index to the whole set. All of
these are simple tools under the control of
shell scripts or makefiles.
See SavaJe docs for the results.
Ed
Regarding the TeX fonts:
The fonts ARE scalable simply by
using the option "magstep" that
magnifies them to an arbitrary size (the fonts are vector designs and
can be smoothly scaled).
HOWEVER, TeX is a system for very
high quality documents and therefore
every font SHOULD BE DESIGNED AT
ITS INTENDED SIZE!
Using a scalable font for 6 point
text, 12 point text and 24 point
text will not provide optimum
results for all these sizes.
If you need the best possible
appearance you don't scale your
fonts. (even though, as I said,
TeX can scale the fonts)
Petros
When developers write documentation - It usually turns out to be little more than digital chicken scratch. Would you hire a meat butcher to perform surgery? Or would you ask a court reporter to represent you in a criminal trail? No, then why do you have developers write documentation? Developers are no more equipped to write documentation than a monkey working on Newtonians Thorium. If your going to invest a lot of time, money and effort into developing software, develop an equal amount of time, money and effort into hiring a professional writer for the documentation. The results from your customer base will be well worth the effort.
Mmh?
So you've been running XP for more than a year, right?
Why not use nroff? It's ASCII-based, very fast, designed to handle VERY large documents, and has been around for at least 30 years, so it's about as stable as you're going to get. Various post-processing packages have been around forever (nroff to PostScript, among others).
-- Ed Carp, N7EKG erc@pobox.com PGP KeyID: 0x0BD32C9B What I'm up to: http://intuitives.mine.nu
dvi2pdfm gives faultless output every time....
This can easily be changed. See the TeX FAQ
Cliff, I had similar experience (problems) with ms word but was enduring them until maybe year ago when it became to much to wrestle every day several hours with "intelligent" application that thinks that it knows how document should look better than I. The last straws were (and I can still reproduce them from time to time): 1) reformating one buleted list in complex document causes automatic reformating of all other bulleted lists in the same document, 2) changing block of the text into some of the header forms/fonts (or in the body text, etc ...) changes all of the sudden location and default font family in which that text is displayed.
It is user (and not the application) who should be in control of the layout of the document and its appearance.
Since I could not avoid writing numerous documents (part of the job), I found following solution that works for me:
i) write document in XML,
ii) transform it (via XSLT) into html,
iii) load that html file into ms word, tweak it, export it in rtf (ms rich tect format) format,
iv) send the document to the other members of group
It took me couple of weeks of my free time (maybe 3 hours for dtd and 20 hours of work on xslt) to
develop the initial DTD and XSLT (this one was moderate pain to do) files, and now I keep changing them as I realise that some new tag or attribute is necessary/handy. XML IDE of choice (XML Spy) is able to display in parallel the source code (of XML) and its appearance as in browser so I can write documents quite rapidly.
Advantages of this approach are
A) separation of content (text and logical organization of data) and appearance/presentation,
B) documents do not depend on the version of any software (xml files is essentialy plain text, editable by any text editor),
C) formating of appearance can be spoiled (by msword) only at the very end,
D) i am planing to learn how to export data in pdf and other interesting/useful formats in the future
E) it is relatively rapid to redisplay partial content of the xml file using different xslt instruction file (so, I do not have to form new data/document file via cut and paste and change from the old one, but, instead, I am using excatly the same data/xml file for multiple presentations).
Downsides:
A) when ms word loads html file and export it as an doc or rtf, it still keeps some trace of "web-pagedness" in it, not allowing me to introduce page numbers and similar. However, that is the obstacle that I can get by at the moment.
B) I would like to learn how to export my xml documents directly to the msword format (ala xslt transformation of xml into html, or fo transformation of xml into pdf). It appears that at the moment there are no free solutions for that problem (at this moment) at the market. Ideally one would have to write only one style-sheet with instructions on how to transform an XML document into .doc. Any suggestions, anyone?
THanks,
Traco
ps. tex/latex is mighty thing to use, but it is comparably slow environment to write documentation in it. Also, it is not so portable into vareity of other document forms (how to produce .doc or .rtf format that majority of users in corporations expect?) Also, to see the display on tex document, one needs to always have parser (miktex, ...) and dvi viever (or ps viewer) etc ..., while xml can always be observed in the "low-tek" environment: just paste it onto ie (internet explorer) and it will be properly displayed.
LaTeX can output RTF (and by that token also MAN), HTML, DVI, PS, and PDF. As far as quality to effort, many organizations have already created formatting classes to produce the desired document format used by many groups of people (for instance, you can get IEEE format easily). BibTeX, which is used extremely frequently with LaTeX, also makes it easy to manage huge bibliography databases. Also, the Math formatting is absolutely spectacular, and I doubt it could get simpler without losing functionality (I don't know that this is true - tell me if you've found the opposite to be true).
What other formats are you looking for? And what do you mean, it has a higher output quality, and lower quality to effort ratio? You need to qualify that.
I think that perhaps you're talking about writing a man or info page. Perhaps an application specifically designed for that purpose is better at it than a general purpose application, but overall, I think that the reason so many more people are using LaTeX for documentation than texinfo is because of its usefulness.
Mod me down and I will become more powerful than you can possibly imagine!
If you're looking to buy a software package for writing online help, RoboHelp is pricey but does the trick. I've been using it for 4 years and even after attempting other tools like DocToHelp (a disaster on wheels, especially since Wextech's been bought out by ComponentOne). You can writing HTML and WebHelp with ease. It still gets my vote time and again.
- DocBook was created exactly for writing technical docs, so it should have all the features you need.
- SGML/XML is portable, can be processed with standard tools -- and XML seems to be the future so your stuff will remain readable for a long time (unlike using some proprietary format)
- Pure text, works with CVS
- HTML and PDF output works out of the box (infinite customization is
possible using DSSSL/XSLT)
However so far I haven't found the perfect tool for writing DocBook. (Someone mentioned Morphon but it didn't work for me -- it was slow, a bit complicated to start with, and crashed all the time (ok, it's beta or something).) Emacs is great but I find it too cumbersome to edit XML/SGML source. I think the LyX approach of WYSIWYM is the way to do structured documents. It makes you concentrate on the content, looks pretty and you can even configure it to use Emacs key bindings. I use it all the time for writing docs, and it's extremely efficient: I just type text as in Emacs, and do all the formatting with a few more keystrokes. LyX was originally designed to be a frontend for LaTeX, but it has DocBook book and acticle document classes as well! It only supports a subset of DocBook but it's evolving. Currently these things work (and I found I don't really need more):I have tested lyx using the docbook class - and it doesn't seem to be perfect.
:-( You can export the lyx file to DocBook.
* It doesn't use docbook to store it's files. Lyx uses *lyx files a they do not contain xml/sgml
* Lyx can not import docbook.
* embedded images doesn't work.
This is version 1.1.6 fix3.
Can you fill me in on some details about using LyX and DocBook? I'm trying to figure out whether that combination can do the following for me:
1. Allow me to write large amounts (500,000 words) of user-oriented doc split up into many topics, each in a separate file.
2. Allow output to be in various forms, including printed, PDF, HTML and CHTML.
3. Allow topics to be collected together in overlapping subsets for different purposes (e.g. to print a document with topics 1, 2 and 3 (along with title page, TOC and index); and at another time to produce a CHTML help system with topics 1, 4 and 5.)
4. Some way of producing cross-references appropriate to the output format. i.e. if I have cross-references between source files (which semantically means a reference from one topic to another), when I produce printed output I want the cross-refs to refer to the correct page number, but when I produce HTML output I want the cross-refs to be hyperlinks between the correct HTML files.
5. Some form of conditional tags which allow different text to be produced for different targets. The classic example is with cross references: I want "See Another Topic on page 64" for printed output, but when the same topic is used in HTML, the text should say "See Another Topic" as a hyperlink. But the requirement is more general: potentially any piece of text or graphics may be marked as conditional for certain output formats.
Lastly, if I want all this to happen, what auxilliary software do I need on top of LyX?
Matt.
You don't even have to rely on Mozilla or Opera to do the transformation for you, both of which can give slightly icky results for paper versions.
html2ps is excellent for nicely formatting HTML as a paged document. It uses CSS, with a few of its own extensions (paper size, table of contents generation, hyphenation, page headers and footers, page numbers, and the like). It can even automatically swap in PostScript diagrams for gifs in the HTML source.
It has the advantage over a browser in being scriptable you can have one makefile that runs HTML Tidy on your source, then converts it to PostScript (and possibly PDF too).
You get all the benefits of a plain text format (CVS, etc), and paper/PDF output that many readers couldn't distinguish from having been word processed.
Smylers
Maybe Mozilla should have used the html2ps code for printing, then. (License compatibility?) Small tools.
Constitutionally Correct
The obvious counter-question to a lot of the comments here is simply "what do you want it for?"
When responding to a posting like the one which started this whole discussion, I think it should be fairly evident that we're talking about a solution which is flexible and scalable enough to be useful even for small documents like manual pages, and yet provide the power to do technically complex documentation with pictures, cross-references, multiple volumes, possibly multiple concurrent versions (a "lite" document and the "real thing" from the same sources, perhaps).
I don't suppose anybody here would have experience with professional tools like Arbortext / Documation / whatchamacallit, at least enough to comment on where they fit into the big picture?
My own list of requirements goes something like this --
All of this points to an ASCII-based format, and Emacs as a pretty darn good primary editing tool.
Also, it pretty much rules out any WYSIWYG editor. (There is no such thing as a "WYSIWYG editor" because editing is an activity where, by definition, you are not out to get what you see, but rather, to create a file which is meaningful both to you and to the computer. Using a word processor for this is completely misdirected.)
I suppose PDF is something a lot of sites require nowadays, although it's not something I particularly care about. (In fact, I hate PDF.)
The future trend here is probably XML with tools for producing HTML and troff output. (I don't know of any tool which does xxxML to troff, any pointers?)
Including images and code snippets should be trivial. Keeping them in separate files should not be hard or clumsy. Conversely, being able to do simple images (and code, of course) in-line would be very nice. (Good old troff with pic macros is pretty usable, if you can find somebody to teach you...)
I've looked at various Literate Programming tools (noweb, POD, etc) and they all fail on some other criteria of mine, although I think the idea is very good indeed. My first gripe with these is that some sort of #include facility is a must, because the documentation file structure should be modular just like the code structure. (Anybody know of a LitProg system which doesn't have this limitation? Also it should preferably not require TeX and/or some particular programming language; I want to be able to document code in any programming language!)
Mathematical formulas are not important in my work, but if they are important to you, TeX suddenly gets to seem attractive (at least until MathML takes off).
This is where I think TeX fails. I should not have to include instructions for italic correction or hyphenation hints smack dab in the text itself. (Is this a misdirected comment with newer versions?)
Style sheets are pretty much a must for anything more complex than five to ten pages.
Again, I have not found any tools that really fit the bill, but it looks to me like XML is pretty much the answer, longer term.
My favorite here is definitely POD. HTML and XML have a terrible signal-to-noise ratio. They're okay for readers, but writing raw xxxML is too clumsy for me.
I guess it's safe to say that troff -- with macros, or without -- is about as user friendly as assembly language...
I'm afraid this came out less structured than I'd like it to be, but it's hopefully useful to somebody nevertheless. (I think it's pretty safe to blame the ridiculously small form submission box, and the inadequate form editor in my web browser. I did produce a first draft in Emacs, but then I had to make modifications...)