Ben,
I think there is a deeper need here. Writing good document is hard and
keeping it in sync with code is harder still.
A book/booklet separates content from the code and being frozen in time
faces obsolescence. I would prefer to see a guidebook framework in Pharo
that every package author can use to create a simple narrative on its
features. Package authors and consumers have an incentive to keep the
code and content in sync. If an Object is a recursion on the notion of a
computer, why not provide, say a Note, as a recursive simplification of
a book?
The framework could be on the lines of Plugins, Tests. E.g.
Package-Core
Package-Plugins
Package-Tests
*Package-Guide*
The guide framework should support active code (say to pop the source
code for a method), active links to guides on which this package
depends, automatic generation of table of contents, index of class
references. Most of features already exists in Pharo but spread all
over. They need a home.
A package could also extend this basic framework with features (e.g. PDF
package could export articles to PDF, Zinc could generate HTML).
Regards .. Subbu
On Thursday 25 May 2017 07:03 AM, Ben Coman wrote:
I've seen a few requests for short bits of code to use in playground for
a demo presentation. I wonder if it would be good to have a booklet to
gather these - seeded with Sven's excellent article...
https://medium.com/concerning-pharo/elegant-pharo-code-bb590f0856d0
It could include the recent meta-programming scripts like searching for
all class instance variables starting with a capital letter.
The book might be named "Snippets", in a format presentable to laser
print on-site - something physical for attendees to take away with them
to quick demo to others back in their office.
I can take the lead in setting it up. Anyone remember any relevant
posts in our archives?
cheers -ben
