Forum OpenACS Development: 4.6.x Documentation; Documentation formatting

I'm working on the 4.6.x install guide. My plan is to get stuff checked in and approved in this order:
  1. Add an Upgrade section
  2. Revision of the Unix/Linux section
  3. Adding VMWare and Mac sections from contributors
  4. Adding a tutorial (covering apm, creating tables that use acs_objects and stored procedures, integration with content_revisions, openfts, notifications, and general_comments; using ad_form and templates)


  1. The release notes on are much bigger than the release notes in HEAD. I'm staring at the most recent version of release-notes.xml (1.5, by jeffd) and they're only ~90 lines. Where is the big, long set of release notes that's up on
  2. Thumbs up or thumbs down to the more visually agressive style ? (compare New style and current style.


    • shading and borders for GUI elements (e.g. Next button)
    • shading for text from the screen
    • differentiating between shell code and program listings
    • highlighting text (servername, password) that should be changed before it's typed in
    • eye-catching green on black for user shell input
  3. Wherever we have shell input, I want to make sure that it can be cut and paste directly into a shell. This means removing the shell prompts, stdout responses, and comments. Stripped shell commands, however, are bad for readability and learning. Here are some different ways to accomplish it:
    • Fancy html tricks so that commentary doesn't get copied. Easier to maintain. Unreliable in use.
    • Duplicate code in place - two columns, or two rows. One readable, one copyable. Could get bulky and confusing.
    • Duplicate code in a separate place. Footnotes to link the inline readable code to a file of copyable code. Possibly hard to follow and harder to maintain.
  4. Does anybody object if I put extensions into the css file - not changing any defaults or current settings, but adding new classes to support more formatting?
  5. FYI - I'm working from HEAD and targeting 4.6.1/4.6.2.
Posted by Talli Somekh on
Rock on, Joel!


Posted by Ola Hansson on

Those sound like really useful additions indeed!

To comment on your questions:

2) Personally, I think I prefer the current style (probably mostly because I've grown acustomed to it). I find the new style a little muddled :-)

3) Hmm.. I can see your point that cutting/pasting should be easy. However, I think we ought to focus on readability, and keeping the prompts makes it much easier for the installer to realize from where and as which user a certain command should be issued. The "first-timer" is probably more anxious about gaining understanding of what's going on during the installation than (s)he is about gaining time.

4) I don't think anyone will object to this.

Posted by Jamie Rasmussen on
I also prefer the current style overall - in particular, I don't like things that look like buttons that I can't click on. I do think some of your enhancements are nice. I think giving the user a few action cues with color is great if not overused. We should also check that users with color vision deficiency won't have problems with readability.

In my Windows install documents, I took a cut-and-paste approach, and it has been very useful. You can put comments in with, e.g.

# Aren't you glad you can cut-and-paste this command?
/usr/local/bin/tcpserver -x /etc/tcp.smtp.cdb -v -u 502 -g 501 0 smtp /var/qmail/bin/qmail-smtpd 2>&1 | /var/qmail/bin/splogger smtpd 3 & 

You could make commands and comments different colors, white and green perhaps. Of course you would still lose any inlined output and prompt information as Ola mentioned. Thanks for working on this!

Posted by Jeff Davis on
I would say that even if this is readable by people we should avoid the bright green on bright yellow since it is very likely to make peoples brains explode :)

I am a big fan of cut and paste things as well. One example of something we might consider is the oracle setup statements page that Lars did. I use it all the time...

Posted by Don Baccus on
Bright green and bright yellow remind me of too many hours stuck in Heathrow waiting for late airplane connections ... :)
Posted by Roberto Mello on
Hi Joel,

Terrific work you've been doing.

I don't think a tutorial should be part of the Installation documents, because, well, it's not necessary for installation. If you already have OpenACS installed (say, from your distribution's install process, it may happen in the future), how would you know there's a tutorial in the installation docs?

The new style, while adding some enhancements, is too muddled for me. Too many colors, button-looking things that are not buttons, bright green on black text that looks like my ancient PC XT terminal.

I especially dislike the huge screens where you just have a long stream of commands for which the user is given no clue what they are for. Is the user supposed to just trust us? Or we could educate the user and let him/her know why we are suggesting him/her to run the next few commands?

For question 1, the longer release notes are only on I posted about it on a thread a while ago. OpenACS 4.6 was released without much fanfare, and wrote the longer release notes after the fact, so I couldn't just add to the Docbook sources and regenerate.

For question 3, cut-and-pasting is good, but I would personally never copy and paste more than a couple lines. In the example you posted, you have a screen full of commands. One can't tell where one set of commands ends and the other starts, and why they are being run.

So if the screens for command copy-and-pasting are short and explained, then we should be ok.


Posted by Joel Aufrecht on

Full-page Mockups of two ways of doing cut and paste shell code. Sorry, the forum won't let me use the style tag, so no examples here.

Posted by Talli Somekh on
I like how in example 2 you add the "copy to clipboard" too. I really liked the way that Lars has it setup, as Jeff mentioned in a few posts before this one, and I think how you utilize the trick here is nice.

That seems to be the ideal way to do it, if it's possible to do in docbook and is cross platform compatible.

Those are big ifs, though. Have you looked into it yet?

Also, the green on black is not that readeable, actually, yellow on black, or black on yellow, are supposed to be the most striking combinations and it's why many street signs utilize the scheme. But that combo is garish as well.

How about hot pink on mauve?


Posted by Andrew Piskorski on
Question 3, the cutting and pasting of shell commands:

Well, personally, I rarely cut and paste shell commands without first copying them into Emacs and looking at them carefully, so having to delete the non-command lines and characters isn't a big deal to me.

Probably the simplest solution that's both easy to maintain and read is to strip out the shell prompt from command lines, and prefix all command lines with a short unique string. Then in the introduction or some appendix, provide the user with a simple command (different flavors, for shell/sed, Emacs, tclsh, etc.) to strip out all lines which are not either a shell command line, or whitespace. Alternately, leave the command lines unprefixed and prefix all non-command lines with some short unique string. I'm not sure which would be better.

Posted by Andrew Piskorski on
Question 2, old vs. new style:

The new style is hideously awful, IMNSHO. All the big ugly button looking things are confusing. That's definitely the strong first impression, anyway! :) Overall, way too much chartjunk. Some of the other changes have merit, though.

Also, I suspect that numbering the steps may actually be counterproductive. These steps are not at all written in stone, and as the document changes all those numbers are going to change. Do we really want people to start referring to "problem in step 19" when the number 19 may well change the next time someone edits the document? On the other hand, for a given revision of the document, being able to refer to steps by numbers is kind of nice.

The attempt highlight the nouns in long lists of instructions like "check Editors", "uncheck Web Server" seems like a good idea, but the strong dark gray color isn't the best choice for this. Light gray should do the trick.

Also, I hope all the special markup is being done with some kind of stylesheet so e.g. the "draw attention to this text" background color can be easily tweaked?

In the old style, I also don't like the dark gray backgrounds very much. Too visually jarring. Backgrounds around all the shell commands are fine, but I'd suggest a much lighter gray color.

Posted by xx xx on

Thanks for your new mockups. However, I would rather see you lose the prompts again. Maybe write the shell prompt at the beginning of each code block or go with Andrew's proposal.
- I think, with prompts, it is less readable even if you would make code bold (example 3) and align code left in a new cell.
- Furthermore, I cannot 'cut and paste' parts of it with 'copy to clipboard'. So I end up with reduced usability.

I loved it the way it was, actually. Some remarks:
- 'if the screens for command copy-and-pasting are short and explained, then we should be ok' (roberto)
- green on black won't work for those with a color deficiency. Check:
- Otherwise, colors, buttons etcetera are ok with me. It's a personal taste. However, a better advice is probably to stay close to the design of the current website. There has been a lot of discussion about it. Probably stay with different types of blue and gray only.
- What about javascript 'tooltips' ?

Posted by Joel Aufrecht on
Okay, to summarize what I've heard:
  • Minimize the change from the current style
  • Keep the style non-aggressive
  • Material for copy-paste must be fully visible before copying so people can see what's in it.

With that in mind, here is my first proposal for updated document style. This is all done in CSS, so it will be easy to continue adjusting. Please let me know if there's something in it that you can't stand, and if so please suggest an alternative. Thanks for the great feedback.

Posted by Don Baccus on
Much, much better, IMO, good work.  I'll let others nit-pick the details :)
Posted by Frank N. on
Joel, I by far prefer your latest proposal #1. I do however have two nitpicks.

*) The 'guilabel' class is too low in contrast, making the button hard to read for people with poor eyesight. I would prefer a subtle variation of the programlisting class for readability, something like this:

.guilabel{background-color:#eeeeee; padding:2px; color:#0000dd;}

*) Konqueror v3.1.0 doesn't render the border on the guibutton class, but you can hardly be blamed for that. Makes the buttons look like normal links with a bold typeface. Looks as expected in Mozilla.

Posted by Vadim Makarov on
The old formatting uses simple tags and looks consistently in different browsers. The new fancy one does not: in particular, IE 5.0 doesn't draw buttons, in NN 4.7 the text is plain broken (what else would you expect? :), and Moz.1.3, IE and Opera all display the gray border around yellow field differently, IE in fact does not display it. I'd say KIS, it's an HTML doc, not a printed page layout.

Colored text is somewhat harder to read for some people.

Posted by Vadim Makarov on
In your first proposal, the frame around buttons is not displayed in IE 5.0, and the last snippet comes as a single line in Opera 5. For the record, it looks readable in NN 4 but still different.

I'm itching to say that if you find yourself debugging something as simple as text formatting, you are overcomplicating things a bit somewhere.

Don't let me start how this is going to look in print from different browsers. Subtle features like fancy shading may well be gone on the printout, and color too. What's gauranteely left on the print is fixed width vs. variable width font, headers, and bold and italic attributes. I think, the old style could be used in print form well.

Please forgive me for only discussing problems. It's easier to critique others than to do something myself, you know :)

Posted by Eric Wolfram on
No matter how you do that shell command thing (I generally copy and paste, fyi, but not groups of commands at a time -- perhaps one command at a time -- step by step.)

Anyway, whatever happens, I would like to help write some docs on how to use this nice ACS stuff. More then installing it, the whole offer could use some user guides and admin guides and real explanations of how the installed code actually solves real problems. The learning curve to understanding all this huge.

Thanks to everyone who also publishes stuff here or on your sites. It's helped me over the years to understand. I've written some docs for 3.2.5. I want to publish some docs for using 4.6 too as I learn more -- I just installed it a few weeks ago
later to be known as:

Some simple docs could help me right now -- even if they're not finished or just screen shots. Even just short overviews or examples for each application. The 4.6 groups admin tool, for instance, could use some real examples of how to set that up to solve real life situations. The relational types, subsites, objects, components, ect -- wow -- that could overwhelm someone ...

Is there a glossery for those terms? Some definitions? Some examples?


Posted by Joel Aufrecht on
Have you looked at the developer's guide? (There's also a copy on your machine, at the same partial URL.)

I would like to add a tutorial to the section, covering the existing topics and some new ones in a much briefer, more howto-oriented way. Here's my list:

  • How to use the APM to start a new package
  • How to write documentation, including self-documenting code
  • How to set up the database tables and procedures for your new package, including:
    • How to create automated install/uninstall/upgrade scripts
    • How and when and why to use acs_objects
    • How to use stored procedures for __new, __delete, and __name stored procedures
    • How to use the content management tables
  • How to make your package searchable with OpenFTS/Oracle
  • How to make your package send email notifications
  • How to use tcl/adp pairs to present pages, including
    • How to use ad_page_contract
    • How to use the template system
    • How to prepare pagelets for inclusion in other pages
  • How and when to put procedures in a tcl procedure library
  • How to add general_comments to your pages
  • How to use a single ad_form to make a page that shows insert/edit forms, validates data, and does the database work. (plan to draw from Jon Griffin's doc)
  • How to add automated regression testing to your packages
  • How and when to implement caching
  • How to isolate database code for portability
  • How to use the html/text entry widget to get the "does this look right" confirm page

All of these should be in the context of one fairly simple package like the notes thing. Anyone who would like to tackle a section, or just send me notes to save me some time, or has more stuff they want to see on the list, please email.

Posted by Dave Bauer on

Would you like to setup a page under the documentation project  ETP section to keep track of this? It sounds great. I would just suggest adding a section on the groups/parties, and permissions system to that.

Posted by Joel Aufrecht on
What's the "documentation project  ETP section?"
Posted by Dave Bauer on

We want to coordinate the documentation effort. To do that I started that section to keep track of tasks we needed to complete. You can see that, so far, we have not had much time to work on the list, let alone the actual documentation. Us being myself and Roberto Mello.

I think, although we have a huge amount of documentation, it is quite difficult to learn how it all works together. One problem is that much of the useful documentation for core packages in the the package documentation, while other vital docs are in the Kernel documenation, or "Developer" documenation.

A tutortial such as you propose would replace the developer section with up to date information, and bring in the useful parts of acs-templating, notifications etc.

Posted by Joel Aufrecht on
  1. How do I edit that page?
  2. What's the best way to get community feedback on doc work in progress? I can keep posting one-offs on my site; I can check stuff into cvs and invite people to look at them through the cvs web interface (e.g., tutorial.html. (I can never find the cvs interface without searching - could this be linked from somewhere prominent like A third way would be for me to maintain a HEAD or pre-checkin instance of the doc package on one of my servers. I'd like to post work-in-progress as soon as it's specific enough that people can see where I'm headed, and before I've gone too far in a direction that people disagree with.
  3. My lists of planned work are ... mostly already detailed in this thread, actually. Here's current status:
    • Add an Upgrade section (already checked in to cvs)
    • Revise the Install Section to:
      • Include most current docs on non-linux installs (started, needs volunteers with those platforms)
      • Include a Reference Install (started; needs community feedback on what a Reference Install should be)
      • Integrate all the supporting software into the flow (not started)
      • Add a maintenance section (not started)
    • Rearrange the Developer Documentation: (in planning)
      • First, a hello world tutorial (like this but shorter)
      • Second, an extended tutorial with standalone sections for each of the topics detailed above
      • Third, the existing material, updated and cleaned up. The difference between the extended tutorial and the current developer's guide is that a tutorial is oriented for learning and the guide is more oriented towards reference. Where possible, I'd even like to consider moving material from the Developer's Guide to the per-package documentation.
Posted by Dave Bauer on

I am not sure where the documents in progress should go. CVS probably would be a good place.

I have given you admin privilege over the documentation project page. If you visit that page, you will see an Edit This Page link at the botton. You can add additional pages as necessary.

Posted by Roberto Mello on
Just so the thread readers are aware, this is what I had planned a year ago for documentation:

We have also discussed several times (in #openacs) the revamping of the developer documents to include more tutorial-like things.

I think improving individual package documentation will go a long way towards making developing with OpenACS easier. This is especially true for new packages.

"No package left behind" could be our motto.


Posted by Joel Aufrecht on
Drafts of about a third of the new install doc are up. In particular:
Prerequisite Software: Individual packages - I would appreciate updates to this. Especially - did I hear that we'll have to upgrade libxml2?
Install Linux and supporting software. Is the visual format acceptable? (caveats: most of the shell sections are still just commands, not a picture of an interactive session; the paths don't reflect the ongoing discussion)
Posted by Dave Bauer on

I don't like to complain. But I really think the visual style is very distracting. Is it really necessary to surround the word "Next" in a grey box, and underline the N in next? I think most people will get the point if you just say "click Next." I feel the same way about the dark grey background sections. It makes it much more difficult to read the text formatted this way.

My advice would be to use a monospaced style for user entered input and limit the amount of text that is displayed as bold.

I also want to thank you for taking on this task! It is greatly appreciated.

Posted by Torben Brosten on
Hi Joel,

The current style has evolved from input from the community. There are basic reasons for keeping it similar. Does it really have to change much?

For instance:

1. Greys (and colors near grey) work best because they are color neutral. That is, they work for people and equipment that are color blind or where a primary color does not work.

2. Italics work best in font sizes that are larger than standard, again because readibility.

3. Sans-serif fonts are generally easier to read.

4. The current doc style is fairly browser display tolerant.

I think there has been some criticism about the use of background colors for highlighting.

You could experiment by making a light grey backround around the outer document boundaries (perhaps a lighter grey background  for the document background) and white to highlight the background of "screen shots" etc.  This would provide visual highlights and may reduce eye strain for those who experience difficulty reading high-contrast screens. However, large grey backgrounds may be a problem if  some printers print the background color. =(

Thick (grey) borders may be enough for highlighting blocks of text, so that varying the background color becomes unneccessary.

Posted by Joel Aufrecht on
The latest evolution of the formatting is visibile here This section is complete, and shows the following:
  • All of the button and label markup is gone except for courier font
  • shaded background is used in blocks to indicate shells and program listings
  • The body font is a surprise. I've actually left it sans-serif through all versions but it's coming out serif anyway. Feedback welcome as I sort through browser settings, site-wide stylesheets, etc, to understand this phenomenon.
  • Bold is used only for text that you enter into the computer, and in headings which are also in a larger font.
  • I've left the "replaceable" text red, because it's also italic and a bit bigger than surrounding text, so it doesn't just rely on color. It's the only italic used.
  • Shell commands are duplicated to make cut-paste easier.