[Oberon] Re (2): suggestions for documentation.

[Chris Burrows]

> -----Original Message-----
> From: peter at easthope.ca [mailto:peter at easthope.ca]
> Sent: Thursday, 3 April 2014 11:34 AM
> To: oberon at lists.inf.ethz.ch
> Subject: [Oberon] Re (2): suggestions for documentation.
> 
> Provided an html respects the principle of browser responsibility for
> presentation, navigation in it is more efficient than navigation in a PDF.
A
> several-hundred page PDF is really a pain to navigate.  

That has not been my experience. Any lack of navigation features in a
particular PDF file is not a limitation of the PDF format. Either the author
has not implemented them or the reader is not aware of their existence. PDF
files have both bookmark and hypertext link creation capabilities.
'Bookmarks' may be a misleading term - they are commonly used to setup a
(collapsible, indented sublevels) table of contents. You can configure the
Acrobat reader so the table of contents is always visible in a sidebar so is
accessible no matter which page you are currently reading. 

If you have a copy of Acrobat you can easily create a table of contents even
if you do not have the original source of the PDF file. I have added a table
of contents to the 2013 Oberon Report distributed with Astrobe. You can
download a copy if you want to see what I mean from:

http://www.astrobe.com/Oberon.htm

When you are viewing it in Acrobat Reader, make sure that you have the 'Show
Navigation Pane' option checked and click on the 'Bookmarks' button on the
navigation pane to show the table of contents. Click on one of the entries
and it will take you to the appropriate page. 

I have also added a list of contents to my own copy of the Project Oberon
2013 book after combining the three PDF files into one. It is about a
15-minute exercise using shortcuts on section headingsI now find it very
easy to navigate.

Also on the website there are links to the NXP reference manuals for the ARM
Cortex-M3 microcontrollers that need to be referenced extensively when
programming these devices. The largest manual is a 1250+ page PDF file.
However, because it has a table of contents and hyperlinks on the pages to
various tables it is very efficient to use. Additionally the Acrobat
Reader's split screen feature (drag down the little rectangular button at
the top of the scrollbar) allows you to access both the original page and
the page it links to simultaneously. 

If you have two PDF files and want to check the difference in content you
can use the excellent difference listing program 'Beyond Compare' with its
PDF plug-in. Great for quickly identifying what has changed in each revision
of the Oberon Report. 

I'm not saying PDF is good and HTML is bad - both are useful for different
reasons. In my case my preferences are PDF for reference books and printed
materials that need to be studied and HTML for webpages and program Help
files that only need to be glanced at. 

Finally, I have to say that I have no more desire to read a book on a
handheld device than I have to cut the lawn with a pair of nail scissors ;-)

Regards,
Chris

--
Chris Burrows
CFB Software
http://www.cfbsoftware.com