Matthew,

Re: Magic Book, I said ages ago that I thought an easy hack would be
to add extra meta-data tags to a PDF, creating an xPDF (extended PDF).
Of course, these hacks don't tend to work all the time on every
interpreter (PDF) imaginable, but it is very possible to write our own
reader that deviates slightly to enable us to use our own private
commands. And anyway, firms like SAP stick loads of weird metadata
inside PDFs. And so does Microsoft's Office program.

There are thus several ways of achieving this:

1) You have 1 PDF per topic and include a b64'd lump of code with it
at the end of the file. [1]

2) You have PDFs that are slightly larger than the one "topic" atom,
and then allow for a new hierarchical (=page based) object
(implemented as a separate PDF-object with no true cross-references
inside the PDF, this data will be read by a private interpreter).

2 with its new metadata, perhaps implemented in some private manner or
as XML or whatever, will then enable one to be able to run scripts on
the page to see whether it is out of date with respect to the Squeak
that is running (the colour coded tests of the Magic Book).

[1] Just to prove this, I've attached a MINIM/RIFFS PDF (the naming
scheme is mine and a friend's), which shows the b64'd stream in
action. You can, of course decode without squeak using WinZip, or
StuffIt, though YMMV.


On 4/5/07, Matthew Fulmer <tapplek at gmail.com> wrote:
> On Thu, Apr 05, 2007 at 01:22:04AM -0700, Matthew Fulmer wrote:
> > >From discussions I have had on IRC with Derek O'Connell, Max
> > OrHai, and Paul Bennett, I have decided it is time to propose an
> > official road map for the Squeak Documentation Team for 2007:
> >
> > We are currently in the formative stages, and a clear goal is
> > starting to emerge, along with a path to get there. We would
> > like to see a Squeak where:
> > - Tutorials exist in the main image
> > - All core functionality is documented and up-to-date
> > - The documentation can be viewed and edited both within the
> >   image and from a central website
> > - The documentation can be easily maintained indefinitely
> >
> > How can we get there? There are several steps we must take, and
> > they can be done mostly in parallel:
> > - Collect all existing documentation together in one place.
> > -- This is nearly complete. We have assembled a list of nearly
> >    all Squeak documentation that exists outside of the image:
> > -- Squeak Tutorials (Links)[1]
> > -- Category Index[2]
> > - Categorize and index all of this documentation.
> > -- We are undertaking this task in the small at Squeak
> >    Tutorials[3], where we are concerned only with categorizing
> >    and indexing Squeak Tutorials. From there, we will probably
> >    use this hierarchy as a basis for our new index. We stand to
> >    gain two things from completing this project:
> > --- A strong core Documentation team, willing and capable of
> >     facing the larger challenges ahead
> > --- A first-pass at a usable introductory guide to Squeak
> > -- The next step will be to fix the problems listed at
> >    Refactoring the Swiki[4], and complete the Documentation
> >    Table of Contents[5].
> > - Implement Magic Book[6], which will allow the Documentation to
> >   be kept up-to-date indefinitely. This will draw from the work
> >   done by the implementors of Sophie, Pier, SUnit, and perhaps
> >   Gjallar
>
> Max OrHai reminded me that we already have an excellent medium
> for storing Squeak documentation, better than Sophie, Pier, or
> anything else:
>
> COMMENTS!!!
>
> This is much more concrete and practical than whatever I was
> thinking about creating, so I replaced this point with a point
> about comments and how they could be integrated into Pier.
>
> > - Get permission and republish the documentation in a form
> >   suitable for distribution and collaboration
> > -- Paul Bennett has volunteered for this task.
> > - Integrate SUnit tests into the documentation. Thanks to the
> >   3.10 release team, there should be plenty of
> >   unit tests by the time we get to this stage.
>
> I edited this to be more explicit about Magic Book and how the
> point is document verification
>
> > A hyperlinked version of this proposal is on the Doc team home
> > page:
> > http://wiki.squeak.org/squeak/808
>
> This has been updated. Get the newer, saner version there.
>
> > With a clear plan and a clear goal, we can eliminate the
> > criticism that Squeak needs better documentation. There are
> > tasks to be done. If this road map seems good to the community,
> > we can start systematically dividing up the tasks and assigning
> > responsibilities. I will divide up the tasks into week-long
> > chunks, so that one can contribute by sacrificing 2 to 10 hours
> > per week.
> >
> > I especially need help from the developers of Sophie, Pier,
> > SUnit, Monticello, and Spoon to evaluate how difficult it will
> > be to:
> > - Create a system for browsing Documentation along side the code
> > - Embed unit tests within documentation so that it can be
> >   auto-tested for correctness
> > - Edit from both the image and the web
> > - Distribute this documentation with the image
> > - Distribute such documentation as part of a packages
> > - Edit the documentation locally and commit it to a central
> >   (official) image/universe and make it available via the update
> >   mechanism (somewhat like a distributed wiki)
> >
> > I know it is late, but tasks 1-4 would make a great Google
> > Summer of Code project.
>
> Screw that. Comments already satisfy requests 1, 4, 5, and 6,
> and, if combined with Pier, probably satisfy request 3 easily.
> Request 2 is Magic Book, and has been moved to the end of the
> roadmap task list.
>
> > Thank you for reading this proposal, and thanks to all who
> > reminded me how important good documentation really is. You know
> > who you are :)
>
> Thank you Max for reminding me about comments.
>
> (I am such an idiot for forgetting about comments)
>
> > [1] Squeak Tutorials (Links):
> >     http://wiki.squeak.org/squeak/792#Links
> >
> > [2] Category Index:
> >     http://wiki.squeak.org/squeak/5871
> >
> > [3] Squeak Tutorials:
> >     http://wiki.squeak.org/squeak/792
> >
> > [4] Refactoring the Swiki:
> >     http://wiki.squeak.org/squeak/2352
> >
> > [5] Documentation Table of Contents:
> >     http://wiki.squeak.org/squeak/2983
> >
> > [6] Magic Book:
> >     http://wiki.squeak.org/squeak/3004
>
> --
> Matthew Fulmer -- http://mtfulmer.wordpress.com/
> Help improve Squeak Documentation: http://wiki.squeak.org/squeak/808
>
>

Russell Hyer
-- 
Diploma: English Law with German
University of Kent
-------------- next part --------------
A non-text attachment was scrubbed...
Name: RIFFS_PK.PDF
Type: application/pdf
Size: 3551 bytes
Desc: not available
Url : http://lists.squeakfoundation.org/pipermail/squeak-dev/attachments/20070406/8cd33f9d/RIFFS_PK.pdf