Forum OpenACS Q&A: PDFs of acs-core-docs

Collapse
Posted by Roberto Mello on
Hi all,

I have finished "porting" the OpenACS Permissions Tediously Explained
document from HTML to Docbook XML. Doing this kind of porting work is
pretty boring, but it is there now.

I have also generated PDFs from the HTML output using htmldoc. I tried
generating PDFs straight from the Docbook sources using the "xmlto"
utility, but it didn't work (no surprise there for Docbook XML tools)
and I didn't have time to tinker.

So where should I put the PDFs? The 3 PDFs add up to about 850 KiB,
and I think it should not be part of the main tarball (in fact, I
think the HTML docs shouldn't either). Should we make a separate
"docs" tarball with them?

On a separate note, does anyone have
images/acs-without-apm-vs-with-apm.png that is referenced in
kernel/apm-design.xml?

Collapse
Posted by David Geilhufe on
Roberto-
Shouldn't the there be a way for a new user to download OACS onto a non-Internet connected computer and still be able to learn the system (i.e. have docs be downloadable)?

I can be convinced that the docs might not belong in the main tarball, but then we need to be very clear on the download page that a complete download of OACS includes two tarballs.

I recognize no one that uses OACS today would need such instructions, but I think our audience for downloading OACS should be new users, not all the same people who already use OACS.

Collapse
Posted by Roberto Mello on
"Shouldn't the there be a way for a new user to download OACS onto a
non-Internet connected computer and still be able to learn the system (i.e.                                                                                    have docs be downloadable)?"

How did they download OpenACS without an internet-connected computer? That seems to be a contradiction to me.

I obviously didn't say that documentation shouldn't be available for download in any form. I just said that it should be separate from the "main" tarball. Every packaging system on Linux, for example, creates separate packages for documentation.

"I can be convinced that the docs might not belong in the main tarball, but then                                                                                we need to be very clear on the download page that a complete download of OACS                                                                                includes two tarballs."

It's pretty simple, actually. If I am a new user and I come to the OpenACS download page, I'll be presented                                                                                                                                                    with the following:

OpenACS-4.6.tar.gz
OpenACS-4.6-core-documentation.tar.gz

Unless I'm someone who can't understand English, that should be pretty obvious that if I need the documentation (because I'm a new user), then I should download it as well.

In fact, this way is more APM-like. acs-core-docs is just a package, one that colud have its own release schedule as well, although it needs to be pretty close to core releases. AFAIK, that's the direction we're moving to.

"I recognize no one that uses OACS today would need such instructions, but I                                                                                    think our audience for downloading OACS should be new users, not all the same                                                                                  people who already use OACS."

I don't think all OpenACS users today are old timers. There are plenty of recent bboard messages to attest to that fact. New or old users should not be forced to download several megabytes more in documentation if they don't want to.

Collapse
Posted by David Burch on
I am a new user to OpenACS 4.x.  OpenACS 3.x had PDF documentation which was very handy for newbies who wished to print out all the documentation for reading away from the computer.  Nothing beats print for reading.

Where was the PDF documentation finally placed?  Printing out individually-linked HTML pages is a pain.

Collapse
Posted by Roberto Mello on
I have PDFs generated for OpenACS 4.x's acs-core-docs. They will be available in 4.6 (I just don't know where, but they will 😊). If you want a tarball now, let me know.