Writing Documentation 583
"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?"
Out of curiousity (Score:5, Insightful)
A point about M$ word (Score:5, Insightful)
versioning (Score:2, Interesting)
try YODL (Score:5, Informative)
http://www.xs4all.nl/~jantien/yodl/ [xs4all.nl]
LYX (Score:5, Informative)
Check out doxygen (Score:5, Informative)
For a real-world example... (Score:5, Informative)
We're using Doxygen to generate HTML and man pages (!) for libstdc++-v3 [gnu.org], 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.
Re:Check out doxygen (Score:3, Informative)
But for user-level documentation, or even developer-level general overviews of source organisation, resource ownership policies, etc..., I'd have to say it's not the idea tool for that. But then, that's not really what it was designed for.
I'd take a closer look at Docbook and the fairly large set of untilities that exist for converting it to HTML, TeX, man, texinfo, etc... Check http://www.oasis-open.org/docbook/
When doxygen's xml/docbook output format is sorted, even this could be moved that way too...
K.
what kind of documentation? (Score:2)
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?
Answers to stupid interview questions (Score:2)
Documentation is not evil! (Score:5, Insightful)
- 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.
Re:Documentation is not evil! (Score:5, Insightful)
ABSOLUTELY!
You should design every object and every function (down to what the functions input and return are) before coding everything. You should be able to write comments on the function (on the function, not in. Even having stubs for the function) before it is written. Then, you know EXACTLY what the function needs to do when you code it. You even have a nice reference doc for your teammates (if you use javadoc with java).
I've taken this approach MANY times, and I can't tell you how SIMPLE it is to code with this. Its like a homework assignment "Write a function foo, that takes two integers, adds them, and returns it as a real". The code practically writes itself. And the project manager usually doesn't have any trouble tying all the objects together.
I might as well add that this is a great technique to make open source work well and fast.
Re:Documentation is not evil! (Score:2)
But that doesn't work at all when you're trying to come up with a new algorithm, experiment with different user interfaces, extend an existing program to do more things, or any one of a number of tasks where you have to "get your feet wet" coding it for a while before you can clearly see the design.
I'm a big fan of rapid prototyping. In my opinion, there's no better way to figure out the best way to program something than to start writing some code.
This does NOT mean that you shouldn't go back and document the code (both with inline comments and external documentation), I'm just trying to argue that it's easy to fall into the trap of overdesigning a program initially, before you really understand the coding tradeoffs you might have to make. Also, there's nothing worse than a fully documented program where the documentation is wrong! I've seen too many cases where the documentation says one thing, but the code does something different because later the programmer realized she needed another argument to a function, and threw it in without fixing the docs.
I guess in my opinion it's not a question of "document, then code", or "code, then document". I have to go back and forth between the two all the time. Initially I write out a short design just so I'm clear what the main goal of the program is. Then I start writing some code. Then I go back and start documenting the parts I coded well, and redesigning the parts I need to redo, in greater detail, and so on.
Re:Documentation is not evil! (Score:5, Insightful)
Sorry, gotta disagree with that. The place of design docs is not to mandate the details, like the exact function inputs and outputs. The place of the design docs is to paint the big picture, perhaps down to assigning the responsibilities to the major building blocks of your code (principle functions, classes, etc.).
Requirements change. This is a fact of life. No real project I've seen since I was a student had requirements that stayed fixed, or even close to fixed, during a whole development cycle. As a result, your design must change.
Furthermore, your initial design will probably be flawed in many ways you don't anticipate until you start trying to implement it. Unless you're copying an algorithm out of a textbook or a design you've used before, you'll be lucky to be even close to your final design on your first pass. As a result, your design will evolve.
If you attempt to record every little detail in the design docs, two things will happen. First, you will cripple the pace of development, as you spend more time updating paperwork than you spend developing. Secondly, your design docs will rapidly become out of date, and hence useless anyway.
The correct place for comments about the details is in the code. This is where you should record the exact input/output parameters of a function, the behaviour in error cases or the meaning of a little helper function. A combination of descriptive names for things and judicious use of comments will do far more for you than a 500 page printout of last month's code base.
Making your code its own detailed documentation allows for fast prototyping -- often the quickest way to find a good basic design -- and for ready modifications as the design evolves. This leaves design docs free to do what they should: recording the overall design.
Welcome to the 21st century, where the waterfall model dried up.
Re:Documentation is not evil! (Score:2)
If you've figured out exactly what every button and form and screen looks like, how they fit together, and how the program will work before you've written a line of code, chances are the coding will go very smoothly.
Prototype the GUI to create the screen shots, and write the documentation. It'll force you to think the entire application through before you start building.
This isn't the first time I've heard of this methodology, and it's not as crazy as it sounds.
In a way, it's kind of like UML - writing all those nine different kinds of diagrams before you start coding - by the time you get to the code, it's all pretty much filling in the blanks - all figured out.
UML is the better way to go, in my experience - you architect the system in advance on a much deeper level than writing user documentation.
texinfo (Score:3, Interesting)
through the emacs formatter and use the formatted ascii output.
So, it's old and limited but still my favorite.
Re:texinfo (Score:3, Interesting)
Texinfo isn't at all limited. In fact, it rocks. It has most of the advantages of LaTeX, it generates beautiful looking html, cross-referenced pdfs, gorgeous postscript, and info files to boot. And the Texinfo-mode for Emacs does most of the tricky bits for you. It builds the menus, makes sure the links all go to the right places, etc. etc.
For computer documentation I personally prefer it over LaTeX (and that's saying a lot).
Doxygen (Score:3, Informative)
dan.
JavaDoc? (Score:5, Informative)
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?
Docbook, docbook, docbook. (Score:5, Informative)
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.
Re:Docbook, docbook, docbook. (Score:4, Informative)
I finally found Morphon's XML Editor [morphon.com] and have been quite happy with it for editing DocBook documents (despite the fact that it's currently a beta version that will crash once in a while).
Re:Docbook, docbook, docbook. (Score:4, Informative)
It's a bit of a pain to set up, but once it's going, it's great (much like most of Linux, I find
My only complaint about docbook is that it (currently) doesn't do math too well -- I use Walsh's stylesheets, and they don't seem to grok MathML yet -- so I have to stick with LaTeX for some things still. Oh, and its table support doesn't seem to be complete when using the TeX backend, so things may come out in unexpected ways.
Re:Docbook, docbook, docbook. (Score:2, Informative)
If your distro doesn't have a docbook package then it can be a major hassle building and setting it up from scratch.
Possible solution (Score:2, Insightful)
convert simple html to pdf (Score:2, Informative)
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.
----
Re:convert simple html to pdf (Score:3, Informative)
HTMLDOC downloads regularly surpass all of our other products combined, and we are actively developing it to support newer stuff like CSS1/2, XHTML, Unicode text, embedded fonts, etc.
Best of all, of course, is that HTMLDOC is (and always shall be) open-source software, with commercial support for those that need it.
LaTeX seemed the simplest way (Score:5, Insightful)
Re:LaTeX seemed the simplest way (Score:5, Informative)
In addition to producing HTML and PDF with latex2html and pdflatex, there are some other features in TeX/LaTeX that appeal to code monkeys like me.
1. Real include files. For example, you can write a mission statement page that gets included in the front of all your documents. When the mission statement changes, you only have to update it in one place, and all your documents reflect the change.
2. \ifthenelse{}{}{} conditionals. This is really handy when combined with the include files above. I have one set of source files that produce three completely different (but related) documents based on a few \def statements. For example, one's for internal use only and one's for wide release, but I only have to fix typos once.
3. Define (\def) statements. I keep version numbers and product names here. PHB says "We just changed the product name from "iCrap" to "eCrap". No problem. It's even easier than search-and-replace.
4. Comments. I comment the source files the my LaTeX documents. Most the time it's just snide remarks, but sometimes I leave useful comments behind.
%% The behavior described in the next paragraph
%% used to be a bug. Now we charge extra for it.
Another Great Benefit of Java (Score:3, Insightful)
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.
Wiki (Score:3, Informative)
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).
javadoc works well for Java code (Score:2, Insightful)
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
gobeProductive 3.0 (Score:2)
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/ [gobe.com]
HTML, LaTeX, LyX., Word... (Score:5, Informative)
A few notes from my experience:
HTML: easy to write, easy to format. HTML TIDY [w3.org] 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 [w3.org]). Also see Converting HTML to other formats [w3.org].
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!
Re:HTML (Score:5, Interesting)
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 [opera.com] 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.
Word is horrible (Score:5, Insightful)
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.
Re:Word is horrible (Score:2, Interesting)
I completely agree. I want to write in HTML (or some equivalent) and deal with content primarily. Style issues can be left to somebody else that has a clue how things are supposed to "look nice". (I sometimes find myself linking to the W3C Ultramarine CSS, because though I know CSS rules I don't have a sense for style.) If there were a good HTML text (not WYSIWY-won't-G) editor that felt polished (not hackish) I'd love it. Much as I like BBEdit, it's not there yet.
Re:Word is horrible (Score:3, Informative)
No, you're an idiot (Score:5, Insightful)
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.
Re:HTML, LaTeX, LyX., Word... (Score:2, Insightful)
Did you even think of reading the manuals? If I was using a program that uses a paradigm I wasn't used to, I'd read the manual. I mean, you wouldn't expect a functional language like O'Caml to work the same way as an imperitive language like C, would you? It's the same sort of thing, in a way.
Re:HTML, LaTeX, LyX., Word... (Score:3, Informative)
I personally use LyX not only for technical stuff (physics) but also for software documentation. The manual for my most recent project IPython [colorado.edu] was all written in LyX and from the single LyX source I generate html and pdf versions for distribution.
I wrote a little perl tool called lyxport [colorado.edu] that automates the process of generating PostScript, HTML and PDF from a single LyX source file.
With LyX I have a word-processor like environment (but where I can customize everything I want) that handles long, multipart documents flawlessly, cross-referencing, graphics, bibliographies, you name it. And from that single source I get properly subdivided HTML, ready to print PostScript or fully hyperlinked PDF (just remember to use the hyperref package for that).
I have used MSWord for long documents (100+pages, multi-part with included subdocuments) and it is simply a stupid, devilishly bad joke. It can (I've seen it do it) crash and leave a multi-part document corrupted to the point where the only option is to rebuild the global structure from subdocuments, and the overall design is simply moronic.
Latex was designed with books and technical documents in mind. Lyx was designed to offer easy access to Latex's power. And side tools can pull them together into a near-perfect environment for what the original poster wanted. And by the way, LyX also handles DocBook if you're looking in that direction.
LaTeX vs WYSIWYG (Score:3, Informative)
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.
WordPerfect (Score:5, Interesting)
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.
Re:WordPerfect (Score:3, Informative)
Ugh! One time my room-mate lost a few hours of work due to a corrupted WP file. He asked if I could fixed it. About an hour into carefully studying the revealed codes, I decided I needed some help. So I went to Corel's website. There were literally hundreds of ways that WP files could become corrupted. The problem was particularly heinous because this particular file would cause the entire system--not just WP, to lock up when you cursored into the wrong part of the file. We eventually gave up, and my room-mate reconstructed his writings from memory (human memory that is).
Of course, that's just one bad experience. Anyone else care to comment about corrupted files in these programs? Automatic backups are always an option, but my room mate did this on a school machine which went down, and he was unaware of that feature anyway.
Of course the best thing would be to have files never get corrupted in the first place, but if they do it should be easy to recover.
docbook does work, and works well (Score:5, Informative)
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.
No question - use LaTeX (Score:5, Insightful)
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 [circlemud.org], 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 [circlemud.org]. Using pdflatex (NOT ps2pdf), you can also create very high quality PDF [circlemud.org], which includes a real PDF table of contents, cross-references, and URL links. Finally, using latex2html, you can create almost native-quality HTML documentation [circlemud.org]. 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.
Migrating from LaTeX to DocBook (Score:2)
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).
A few... (Score:2)
1. Take a look at literate programming tools, like noweb [harvard.edu] or doc++ [sourceforge.net] (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.
Not to be the obvious, but upgrade to Win2k or XP (Score:2, Insightful)
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
POD (Score:2)
obvious joke, sorry (Score:3, Funny)
...In the trial of the
graspee
Use DocBook and document as you code (Score:3, Insightful)
- 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.Docbook explained by KDE's team (Score:2, Informative)
I used to have a lot of trouble in making Docbook work, until I found out KDE's developers documentation [kde.org].
Install the DocBook parsers and generators:
http://i18n.kde.org/doc/install/ [kde.org]
General docbook information:
http://www.docbook.org/ [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, Donald Knuth & Literate Programming (Score:2, Interesting)
Donald Knuth. "Literate Programming (1984)" in Literate Programming. CSLI, 1992, pg. 99. [literateprogramming.com]
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
HappyDoc (Score:2)
It does a really nice job generating (HTML, text, etc.) documentation from python code __doc__ strings and source code.
Some things I used to use... (Score:2)
Nothing beats BBEdit though, nothing. It's only for Macs, which is killing me since I haven't bought a Mac lately.
Another vote for LaTeX here (Score:5, Insightful)
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.
Ten Reasons Why TeX/LaTeX is Better than Word (Score:5, Insightful)
Re:Ten Reasons Why TeX/LaTeX is Better than Word (Score:3, Funny)
Unless you count the liveware virus that makes you want to escape every period\. I'd call that pretty macro\.
FrameMaker?? (Score:2, Insightful)
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.
Adobe Framemaker (Score:2)
The downsides are that it's expensive (~$800), and it's made by the people who sicced the FBI on Dimitry Sklyarov.
The Best Solution (Score:3, Interesting)
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. [corel.ca] The latter two aspects put Ventura in the lead by several lengths, in my opinion. A feature comparison is available here. [coreluser.com] (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.
Ventura still scares me. (Score:2, Informative)
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.
roff (Score:2, Insightful)
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.
Pod - Perl's Plain Old Documentation (Score:2, Informative)
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.
FrameMaker + mif2go = almost any output you like. (Score:2, Interesting)
Try FrameMaker 6.0 [adobe.com] and mif2go [omsys.com] 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.
Docbook clarification (Score:2)
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
DocBook is my choice (Score:2, Informative)
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!
Ever hear of NegWeb or NoWeb? (Score:2)
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 [boswa.com] is simpler, NoWeb [harvard.edu] 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.
XML, XSLT and Docbook - a near-perfect solution (Score:5, Interesting)
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.
In praise of DocBook (Score:5, Interesting)
- 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.
--PhilRodApache Cocoon... (Score:3, Informative)
Use an Outliner (Score:3, Interesting)
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.
Be a little wary of DocBook (Score:4, Interesting)
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 [apache.org]. 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.)
texinfo or docbook (Score:3, Informative)
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 [slashdot.org] and 2819778 [slashdot.org]
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 [ericsson.se] by Roar Smith [mailto] for a simple way to push out your installed info docs.
Here's the GNU Texinfo [gnu.org] documentation.
The only other acceptable format, IMHO, would be docbook.
Re:PEBKAC (Score:5, Insightful)
If an application crashes, it's the developer's fault. Period. End of story. It is NEVER the user's fault.
To answer the article's question. I recommend LaTeX, LyX [lyx.org], latex2html (comes with LaTeX), and dvipdf (comes with ghostscript).
--Bob
Re:PEBKAC (Score:3, Interesting)
Sometimes it is the hardware, malicious programs, other programs, or the operating system too.
You're right that it isn't the user's fault, but the blame can fall on any of the developers of any running software or hardware on the system, not just the application's developer.
Or, to sum it up, blame microsoft since they do it all
Re:PEBKAC (Score:2, Funny)
Re:PEBKAC (Score:3, Interesting)
I would edit your statement to say something more along the lines of:
If an application crashes while being used as it was intended, it's the developer's fault.
Re:PEBKAC (Score:2)
Re:PEBKAC (Score:2, Informative)
1) The generated pdf files are larger than necessary, since semantic knowledge of the document has been lost between source and dvi forms.
2) All hyperlinking is lost. pdflatex does a wonderful job of hyperlinking, whereas dvipdf does not have enough information to do so.
Jason Evans
This monkey gets insightfull? (Score:2)
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
Re:PEBKAC (Score:2)
True. And when a car is crushed, it is the auto maker's fault. A well designed car would be strong enough to be undented even when by two freight trains simultaneously.
Also, mechanical problems are the auto maker's fault even if the car owner replaces the every component of the drive-train with completely different ones from other cars and uses tractor tires and runs on kerosene instead of gasoline and uses dishwater in place of oil.
(Translation: developers CAN develop the perfect, uncrashable app, but there are many competing constraints; cost is not the least of these. And in a Windows world, developers should not be blamed if their application fails to function because the user has upgraded the OS three times and said "Yes" every time an application asks "The current version MSVCRT40.DLL is newer than the copy replacing it. Replace it anyway?")
Re:PEBKAC (Score:2)
I poured lead shavings all over my computer and monitor. Since you've proven it isn't my fault that the programs don't work right, I'm gonna go sue Dell!
Maybe you shoulda said "most crashes" instead of "all"??
StarOffice 6 XML. *waves goodbye to Tex forever* (Score:3, Informative)
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.
TeX gone? Nope. (Score:4, Interesting)
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
Re:PEBKAC (Score:2, Insightful)
It's a word processor, not a hardware driver. Unless ALL your apps are crashing, it's the software developer's fault.
Misconfigurations?
Again, the developers fault. The application should perform predictably and not crash for all possible combinations of configuration. You cannot possibly prescribe or predict what users will do with your application that you might not have anticipated.
If it was a linux program, would you say the same thing?
Absolutely.
--Bob
Re:PEBKAC (Score:5)
A car crash isn't the same as an application crash, sorry.
Almost all application crashes are the developers fault. Only a very tiny percentage (< 0.001%) of application crashes are ever the users fault. Some of them may happen because the hardware or OS is buggy. But, that's not the user's fault. If the user goes into the registry and totally mucks it up, it still isn't the users fault. Even under Linux. If the user unplugs cards randomly from a non-hotswap PCI bus, that's the users fault. If the user breaks their system in some physical way, it's their fault. It is not ever acceptable behavior for a program to crash in the absence of a physical problem with the computer.
Re:PEBKAC (Score:3, Insightful)
Re:PEBKAC (Score:2)
So you expect an Application to work fine when, say, a specific graphics driver blows its stack when you use a brush created in a certain address-range in memory?
Sure, you can handle errors, but if you can crash the *DRIVER*, and the user-mode portion of *that* is what crashes the app, then what are you going to do?
Re:PEBKAC (Score:2, Insightful)
...as for the article, LaTeX is always good (even for writing letters), Doxygen with C++ seems pretty good, too, but, as always, plain text is best.
Windows Crashing, taking Word with it. (Score:2)
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--
Re:PEBKAC (Score:2, Insightful)
Ive been using MS-Word for years too, many versions, on anything since MS-DOS4 to W2K. There are things I dont like in Word, but stable it is.
For example, my home machine runs Windows like a charm, but if I run Linux/XFree86/KDE/Mozilla and load a page with a few large jpgs (which IE would just eat) it begins to swap and stop responding to *any* imput except for the power CHORD! Once I just let it spin to see how long it would take. AFter 2h40min I gave up. I am sooo obviously doing something wrong, I just cant figure out what it is. So dont tell way0utwest to shut up, hes tryin gto help and giving sound advice.
Re:PEBKAC (Score:2)
I knew one person who could crash not only every computer she ever worked with but also managed to crash telephones with amazing regularity... I suspect the cause here is electromagnetic
But aside from these rare instances, program crashes are the result of bad code somewhere, not the result of anything relating to the user. Code, ideally, should be designed to stand up to all user experience.
Re:PEBKAC (Score:2, Informative)
Correct and complete error checking is difficult, and I've messed it up more times than I'd like to admit. But darn it, I do try. I once had a professor who showed us two versions of the same program, one with error checking, and one without. The one with was easily four or five times as large as the one without. On the other hand, it didn't crash. (As far as I know.)
It's not the same as driving a car. Within an application you can anticipate all possible ways of use and limit the user to those things which make sense. An auto manufacturer can't keep a stupid person from driving into a brick wall without causing the car to be useless in the process.
Sean.
I switched (Score:5, Insightful)
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).
Re:TeX? (Score:2)
Diff'ing (Score:2)
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.
I think it is... (Score:2)
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?
Re:And after you're done? (Score:2, Funny)
Is that because you'll sit back and eat lots of twinkies? I think the word you are looking for is expendable.
I wouldn't do that... (Score:2)
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.