Comments about Documentation in .odt & .pdf

(OOo=OpenOffice.org -> http://openoffice.org)

1. Download and open the latest .odt file from doc.tw.o sftp server, under the ./doc.tiki.org/files/ directory. By the time of this writing (and for this example) it is Tiki198beta_21.odt.
2. Make your changes to that file (copy & pasting updated information from current wiki pages at doc.tw.o).
   • Remember to break image links from the pasted images (in OOo: "Edit > links > break the links"), since before that, they would be requested to the doc.tw.o server each time, and we want those images to be inside the .odt document (so taht the odt contains everything even if a person is offline when opening that .odt file).
3. Save a short log of your changes at the page at the beggining for that purpose, and at this wiki page (so that other editors watching this page will notice that you've made a new version of the .odt and .pdf files)
4. Save a copy of the .odt with another name (with a consecutive number or date), just before the following two steps. For instance: Tiki198beta_22.odt
5. Save the file again as Tiki198beta_22_with_alphabetical_index.odt
6. Add all the tags for the indexes and tables of contents (This step may take a looong while for your computer to complete).
   • to do so, you need to go the alphabetical index at the end of the .odt file, right click on it, and select the "edit index/table" (or similar dialogue in your language).
   • there, at the "Index/table" tab (the first one), you have an option called: "Concordance file". Press on the button File on its right, to select the concordance file with the keyword that OOo will search their location in the document to make there the alphabetical index. Select the Tiki198_odt_concordance_file.sdi as a concordance file (you can download it also from ./doc.tiki.org/files/ directory from the sftp server.
   • press ok, and let it take its time (coffee/tea time for you?).
   • Note: the concordance file contains too generic words, still, which produce too many page numbers for those words. You can play with the other options next to "concordance file" setting in that OOo dialogue, in order to improve the final alphabetical index produced. However, once you have run a concordance file in that document, tags are inserted everywhere, and I'm not sure if they can be esily removed. That's why you saved the file as a backup with another name just before adding those tags from the concordance file. Repeat this procedure (with a second backup pree-adding tags, if needed) with other options, or with a smaller concordance file.
   • You can edit the concordance file with the spreadsheet file from which it was generated (Tiki198_odt_concordance_file.ods).
7. Once you like alphabetical index produced in the .odt file, save your file. Remember that it should be the file name like: Tiki198beta_22_with_alphabetical_index.odt
8. Press on the pdf buton in OOo. This file will be generated: Tiki198beta_22_with_alphabetical_index.pdf
9. Upload your files to ./doc.tiki.org/files/ directory:
   • Tiki198beta_22.odt
   • Tiki198beta_22_with_alphabetical_index.pdf
10. Once the upload is finished, delete old symlinked Tiki19beta.pdf and Tiki19beta.odt (they are the links called from the web pages at doc.tw.o; they were point to the files of previous to your version of the odt and pdf files)
11. Create on the remote host (through opening an ssh session) the new Symlinks to your updated files
    
    Copy to clipboard

    ln -s Tiki198beta_22_with_alphabetical_index.pdf Tiki19beta.pdf
    ln -s Tiki198beta_22.odt Tiki19beta.odt

12. Done! (afaik)

• "All of the internal links are weblinks. Shouldn't they link to other pages in the PDF instead? For example, on page 31 there's a link for FEATURES. Shouldn't it simply go to page 109 (Tikiwiki features)?" (Rick)
  'it's a pity the interactive links from the pages are linking to the internet instead of the PDF pages - would it be hard to change using some script ?' (luci)
  • I don't know how to do that (Xavi). I hope a more skilled person can take care of that....

• "It would b nice if each page (or section) had a link back to tw.o (so readers could instantly/easily get the most current info)" (Rick)

• 'use "Real name" instead of login name for the list of authors' (luci)
  • I can't get this information easily. If somebody gives me their real names, I'm glad to add them to the document.' (Xavi)

• 'for links pointing to internet would be better (for printing purposes) if they showed up in a bracket after the link the real URL' (luci)
  • Yes, that would be nice. If any body know an automatic way of handling this for the whole document... (otherwise, I will not do it myself, at least. Xavi)

• "Also, some plugins listed there aren't in the default installation, so users might be confused about why they don't see them at their own site. Probably the non-default plugins should be deleted from the list or identified as extras in some way. " (Gary)
  • I agree. This is a "ToDo" even in v18 still...

• "Well, looking at the doc pages on plugins, I wonder if default plugins should be marked as such there, and plugins from mods.tw.o or other outside sources be in a separate list. Or if they're all listed together, the default ones should at least have an asterisk or something." (Gary)
  • mmm... (Xavi)

• v17: "The table of contents items are not hyperlinked. This make it useless as a navigational feature." (Rick)
  • Included in v18 (Xavi). I finally learned how to do it with Open Office..., a bit tricky...

• v17: "The Acrobat bookmarks are not hierarchically correct. Should they be identical to the presentation of the table of contents?" (Rick)
  • Included in v18 (Xavi)

• v17: "Needs an index. Studies show that a keyword index is the #2 (right after search) preferred method of navigation." (Rick)
  • Included in v18 (Xavi). I've also added the file "Tiki198_odt_concordance_file.ods" in doc.tw.o server, from where the "Tiki198_odt_concordance_file.sdi" was generated top make such alphabetical index.

• v17: 'use "Tikiwiki 1.9.x" instead of "Tiki v1.9+" in the manual main title' (luci)
  • Included in v18, but as Tikiwiki 1.9+, since documentation is mainly for 1.9.x, but some pages are also for 1.10 only...(Xavi)

• v17: 'use "Tikiwiki Documentation" only in the page headers' (luci)
  • Included in v18 (Xavi)

• v17: "Tikiwiki GeoCMS"? -> "Tikiwiki CMS/Groupware"(Gary)
  • Included in v18 (Xavi)

• v17: "Will the non-English plugin descriptions on pages 177-181 be replaced for the final .pdf?" (Gary)
  • Fixed in v18 (Xavi) . Thanks, I didn't notice before...