[squeak-dev] DocCustomHelpToOrg toFile: TerseGuideHelp   looks perfect.

gettimothy gettimothy at zoho.com
Sun Sep 5 18:03:21 UTC 2021

howdy all

location: 'https://www.squeaksource.com/Doc' is producing  some very nice output  for most CustomHelp subclasses.

Attached is a screenshot of  DocCustomHelpToOrg  toFile:  PostgresV3Help

with various levels folded and un-folded.

Thanks to all who helped on the Streams approach, the code looks clean imho

toFile: aCustomHelp

      "DocCustomHelpToOrg  toFile: TerseGuideHelp."

      |ios filename output|

filename := ((aCustomHelp  name  asString), '.org').

output :=  ReadWriteStream on: ''.

aCustomHelp  allSubclassesWithLevelDo:

      [ : eachClass : lvl |


      ios := (String streamContents:

            [ : stream |

                  lvl timesRepeat: [ stream nextPutAll: '*' ].

                  lvl = 1


                              stream nextPutAll: '  '.

                              stream nextPutAll: eachClass bookName]


                              stream nextPutAll: '  '.

                              stream nextPutAll: eachClass bookName.

                              stream nextPutAll: '  class(' , eachClass  name , ') '].

                  stream nextPut: (Character cr).

                  stream nextPutAll: (self toStream: eachClass level: (lvl +1))]).

                  output nextPutAll: (ios contents)]

      startingLevel: 1.

StandardFileStream forceNewFileNamed: filename do: [ :file |   file nextPutAll: output contents ]

There are a couple of caveats.

First some generation errors....

      DocCustomHelpToOrg  toFile:  HelpOnHelp  goes into an infinite loop.  (it shows up ok on http://menmachinesmaterials.com/SeasideDoc)

      DocCustomHelpToOrg  toFile:  MetacelloConfigurationHelp.  "has a builder and pages is empty"

Second, some internal limitiations.

      I make no allowance for a Subclass of a Help being in the superclass pages #()  so some things will get rendered twice.

      since I DO treat subclasses of a CustomHelp to be output in org.

Third, differentiating between a class and a "page" on the .org output requires a clumsy hack.

      I preface the bookName with (class) .

      You can see this in the screenshot.

      Typing this, I just realized that I will need a class name in there so I will know what to name the class when I go from Org to CustomHelp . I will fix that now. (done!)

Fourth, there is some <cough>enhanced</cough> markup in some of the help pages that is Org markup and other wierd stuff.

All that said, my primary mission is to go from Org to CustomHelp.

The "Why" is that for my XTreams Parsing project I will have to learn the Monty XML packages and I want to create the help for it as I study it.

I run into that stuff a lot.

Another "Why" is Eliot and his request for Pragma design patterns help.

Its much easier to write and edit an foo.org file and then (once I write the engine) automagically write the CustomHelp classes from it.

I will start that coding tomorrow.

I will be making a PEG grammar for the task and the callbacks will do the class generation for me (i hope)


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.squeakfoundation.org/pipermail/squeak-dev/attachments/20210905/24f9751c/attachment-0001.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: PostgresV3Help.png
Type: image/png
Size: 41858 bytes
Desc: not available
URL: <http://lists.squeakfoundation.org/pipermail/squeak-dev/attachments/20210905/24f9751c/attachment-0001.png>

More information about the Squeak-dev mailing list