Forum OpenACS Development: document builder from xowiki pages

Posted by Torben Brosten on 01/10/07 01:47 PM

Hi all,

The Documentation Project[1] is currently exploring ways to generate various documenation[2] in xowiki to meet the various needs of readers.

Is there some way to build a document (book) from xowiki pages that are listed in a separate xowiki page (like a table of contents)?

The "multiple perspectives" approach assumes it can be done. A few weeks ago on irc, Gustaf demonstrated a way to request an xowiki page's content without the templated page that wraps around it. I lost my notes about it. Other related tasks have been demonstrated suggesting that publishing documentation from multiple perspectives is entirely feasible.

Perhaps another approach to publishing multiple xowiki pages as one document would be more practical. For example, choosing a xowiki page, and have a magic button collect, organize and somehow publish the results of spidering N links deep (in the xowiki instance) from the current page as one document.. to later be edited. Or maybe create documents based on the primary xowiki page categories.

If you have any ideas on how to create documents from multiple xowiki pages, or know of any existing ways, or want to code a way etc etc, please state them here.

OpenACS 5.3 is in beta, and it would be really really wonderful to have some excitingly useful documentation be published along with the great new features that will be included with it.

I'd be glad to elaborate,

Torben

1. https://openacs.org/xowiki/en/Documentation_Project_Plan
2. https://openacs.org/xowiki/Documentation_Project_Discussion

2: Re: document builder from xowiki pages (response to 1)

Posted by Torben Brosten on 01/11/07 03:55 PM

OpenACS 5.3 is planned to be released this weekend[3].

Gustaf provided these 2 alternate views of xowiki pages:

https://openacs.org/xowiki/docs-end-user?master=0

https://openacs.org/xowiki/docs-end-user?template_file=view-links

So, someone with admin access to openacs.org, could write a short script to create a long static, html page from a page containing xowiki-style local urls (such as [[en:docs-end-user]] ) where the script pulls just the page content for each url: https://openacs.org/xowiki/docs-end-user?master=0 and maybe inserts a css page break between them.

Anyone have some time to tackle this?

I'll start creating the url sets to parallel the docbook toc here: https://openacs.org/doc/current/index.html

3. https://openacs.org/forums/message-view?message_id=553548

3: Re: document builder from xowiki pages (response to 1)

Posted by Gustaf Neumann on 01/11/07 05:04 PM

technically, there are many ways of producing "books" from xowiki pages. have you seen the examples screen shots in:
https://openacs.org/forums/message-view?message%5fid=544971 ?

in any way, you need a way to define a page order and maybe additional filtering criteria. in my opinion "spidering n levels deep" does not make much sense. there are no "primary categories". I am not very happy about the categories of the openacs.org/xowiki, since orthogonal concepts are pushed into a single category tree, where one needs a polydimensional categorization. for example, for each package, there could be code statistics and requirements, documentation of the package, future plans, etc. For example, "kind of documentation" and "package" are orthogonal concepts. There should be certainly some requirements engineering for the categorizations...

The pure liberal wiki-approach is great for building a knowlege base, producing good documentation requires more governance. ... have to rush...

4: Re: document builder from xowiki pages (response to 3)

Posted by Torben Brosten on 01/11/07 09:23 PM

Thanks for pointing out xowiki .42. I read it, but did not comprehend it's significance here.

"in any way, you need a way to define a page order and maybe additional filtering criteria."

Yes, creating a separate "table of contents" (TOC) page seems consistent with that.

"spidering n levels deep" does not make much sense. there are no "primary categories".

For formal documentation, you are right (perhaps by definition?).

"I am not very happy about the categories of the openacs.org/xowiki, since orthogonal concepts are pushed into a single category tree, where one needs a polydimensional categorization. for example, for each package, there could be code statistics and requirements, documentation of the package, future plans, etc. For example, "kind of documentation" and "package" are orthogonal concepts. There should be certainly some requirements engineering for the categorizations... The pure liberal wiki-approach is great for building a knowlege base, producing good documentation requires more governance.

Yes. Good point. I have left categories to those who prefer to use that method to access content. As I see it, readers should be able to find content within 5 or 6 clicks from a well organized TOC --no categories required. Maybe we can get categories to comply with general documentation requirements --even if it means giving categories a separate requirements page to start with ;)

5: Re: document builder from xowiki pages (response to 4)

Posted by Malte Sussdorff on 01/12/07 08:56 AM

How about starting by adding sections to the xowiki pages just as we have from the full import of the official documentation at https://openacs.org/test-doc/ ?

6: Re: document builder from xowiki pages (response to 3)

Posted by Torben Brosten on 01/12/07 11:43 AM

They do exist (but were not easy to find). Now are added to the xowiki home page. Will add TOC's to them.

7: Re: document builder from xowiki pages (response to 1)

Posted by Torben Brosten on 01/12/07 02:27 PM

Okay, here's one way to build a document page from multiple xowiki pages.

1. First create TOC's for each of the main sections using internal links.

2. When ready to build a document from the toc, create a new page with a copy of the TOC, and replace the double brackets [ ] of the internal links with double braces { }. Content is dynamically imported to the one page document.

8: Re: document builder from xowiki pages (response to 1)

Posted by Gustaf Neumann on 01/12/07 10:13 PM

Btw, here is an alternate view of the "old" documentation: In addition ot the ajax based fade-in/fade-out effects, one can see it as one-page book: https://openacs.org/test-doc/book

not very efficient for the everyday usage (would most probably create a static verison and/or run htmldoc over it, but still quite handy....

9: Re: document builder from xowiki pages (response to 1)

Posted by Torben Brosten on 01/14/07 09:55 AM

wow. Add a way to run some safe db queries through the wiki, and you'll have the framework needed for manufacturers to publish manuals --even difficult ones where each product is essentially a prototype or unique/custom order.

10: Re: document builder from xowiki pages (response to 9)

Posted by Gustaf Neumann on 01/22/07 01:36 AM

xowiki has multiple options for filtering information. the actual version of xowiki has filtering for books per categories and allows "and" and "or" operations for the filtering.

To demonstrate these features, i have added a category tree "audience" with "beginner", "developer", "contributor" to openacs.org, mapped the tree to test-doc, and categorized a few pages. Here are the results:

Book for contributor
https://www.openacs.org/test-doc/book?category_id=578376

Book for developer
https://www.openacs.org/test-doc/book?category_id=578363

Book for contributor or developer
https://www.openacs.org/test-doc/book?category_id=578363|578376

Book for contributor and developer (pages having both categories)
https://www.openacs.org/test-doc/book?category_id=578363,578376

The same filtering works not only for books, but also in the single page mode. In the following example, the table of contents contains only the pages categorized for beginners.
https://www.openacs.org/test-doc/?category_id=578361

Best regards
-gustaf neumann

11: Re: document builder from xowiki pages (response to 10)

Posted by Malte Sussdorff on 01/22/07 07:31 AM

Excellent. Exactly what I was looking for. Merci vielmals.