Re: Pumping FFI documentation
Locked
 
|
Hi Guillermo,
I forked the uFFI booklet repo, branched your "version2", and revised & expanded the introduction section of the first chapter... I decided that before I got too far, I should submit a pull request for just that much and get some feedback in case I need trajectory tuning. Your prose is easy to edit. :^) And it looks like my submission promptly broke Travis... Oops. -Ted Guillermo Polito wrote > Hi Ted, > > I split this in a separate thread to avoid noise :) > >> El 23 sept 2019, a las 23:14, Brainstorms < > wild.ideas@ > > escribió: >> >> Guillermo, >> >> I'm interested in helping, but at this point, I think I'd be most helpful >> working at improving documentation (mainly editing) rather than working >> on >> Pharo code itself. (I'd like to work toward that, though.) > > I’ve been doing a pass on the structure, and I was thinking on a rough > structure as follows: > 1) Intro to FFI (callouts, function and library lookup, intro to value > marshalling) > 2) Marshalling (sending arguments, literal arguments, more on > marshalling, basic C types: ints, floats, pointers and how they are > transformed to pharo objects and vice-versa…) > 3) Complex types: strings, unions, arrays, opaque types > 4) Derived types on the Pharo side: How to design nice classes with all > this > 5) Callbacks > 6) Memory management > > I did already a pass on 1), and I got blocked in 2), though I want to > release a version of it this week. > > If you’re up for it, there are several things we can do: > - review the english :) > - give feedback on what is missing, what is not understandable, what can > be explained better > - testing the examples? > >> >> I'm still a newbie with Pharo, but I am a good writer/editor. And I >> expect >> that working with Pharo documentation would be another means of >> increasing >> my knowledge of the Pharo ecosystem -- so that's additional incentive for >> me. > > Cool :) > >> I gather that the PDF books are written using Pillar, which I know >> nothing >> about. Are there resources & guides for this tool/format that would help >> me >> learn how to make & edit these kinds of documents? > > Pillar is a markup syntax (from Pier’s CMS, if you know it). > https://github.com/pillar-markup/pillar > <https://github.com/pillar-markup/pillar> > > Pillar comes with a document model, parser and generators to html, pdf > (through latex), and others… > In Pillar’s readme there are the installation instructions + usage. > > If you check the travis file in the ffi booklet repository > > https://github.com/SquareBracketAssociates/Booklet-uFFI/blob/version2/.travis.yml > <https://github.com/SquareBracketAssociates/Booklet-uFFI/blob/version2/.travis.yml> > > You’ll see it is built with pillar 7.4.1. In other words > > # install pillar > $ git clone https://github.com/pillar-markup/pillar.git -b v7.4.1 > $ cd pillar && ./scripts/build.sh && cd .. > > # go into the booklet repository and build the pdf > $ ./pillar/build/pillar build pdf > > Although you’ll need a mostly up-to-date latex version (latexmk required, > plus several other packages, check Pillar’s readme) > >> Also, I've never contributed to an open source project; Pharo seems to be >> a >> good place to start doing so. I see that most of the documentation, web >> pages, booklets, etc. are in English so there's the advantage that >> English >> is my first language (and I actually paid attention in school :^). I'm >> also aware, from experience, that Documentation is rarely the first >> choice >> for developers to apply their time & enthusiasm… > > And it’s super important nevertheless ^^. > > Guille -- Sent from: http://forum.world.st/Pharo-Smalltalk-Developers-f1294837.html |
Re: Pumping FFI documentation
|
|
> El 29 sept 2019, a las 6:13, Brainstorms <[hidden email]> escribió: > > Hi Guillermo, > > I forked the uFFI booklet repo, branched your "version2", and revised & > expanded the introduction section of the first chapter... > > I decided that before I got too far, I should submit a pull request for just > that much and get some feedback in case I need trajectory tuning. > > Your prose is easy to edit. :^) haha, thanks! I saw it and merged it already :) > > And it looks like my submission promptly broke Travis... Oops. I’ll check it locally, probably there is a silly pillar syntax error somewhere that generates broken latex... > > -Ted > > > > Guillermo Polito wrote >> Hi Ted, >> >> I split this in a separate thread to avoid noise :) >> >>> El 23 sept 2019, a las 23:14, Brainstorms < > >> wild.ideas@ > >> > escribió: >>> >>> Guillermo, >>> >>> I'm interested in helping, but at this point, I think I'd be most helpful >>> working at improving documentation (mainly editing) rather than working >>> on >>> Pharo code itself. (I'd like to work toward that, though.) >> >> I’ve been doing a pass on the structure, and I was thinking on a rough >> structure as follows: >> 1) Intro to FFI (callouts, function and library lookup, intro to value >> marshalling) >> 2) Marshalling (sending arguments, literal arguments, more on >> marshalling, basic C types: ints, floats, pointers and how they are >> transformed to pharo objects and vice-versa…) >> 3) Complex types: strings, unions, arrays, opaque types >> 4) Derived types on the Pharo side: How to design nice classes with all >> this >> 5) Callbacks >> 6) Memory management >> >> I did already a pass on 1), and I got blocked in 2), though I want to >> release a version of it this week. >> >> If you’re up for it, there are several things we can do: >> - review the english :) >> - give feedback on what is missing, what is not understandable, what can >> be explained better >> - testing the examples? >> >>> >>> I'm still a newbie with Pharo, but I am a good writer/editor. And I >>> expect >>> that working with Pharo documentation would be another means of >>> increasing >>> my knowledge of the Pharo ecosystem -- so that's additional incentive for >>> me. >> >> Cool :) >> >>> I gather that the PDF books are written using Pillar, which I know >>> nothing >>> about. Are there resources & guides for this tool/format that would help >>> me >>> learn how to make & edit these kinds of documents? >> >> Pillar is a markup syntax (from Pier’s CMS, if you know it). >> https://github.com/pillar-markup/pillar >> <https://github.com/pillar-markup/pillar> >> >> Pillar comes with a document model, parser and generators to html, pdf >> (through latex), and others… >> In Pillar’s readme there are the installation instructions + usage. >> >> If you check the travis file in the ffi booklet repository >> >> https://github.com/SquareBracketAssociates/Booklet-uFFI/blob/version2/.travis.yml >> <https://github.com/SquareBracketAssociates/Booklet-uFFI/blob/version2/.travis.yml> >> >> You’ll see it is built with pillar 7.4.1. In other words >> >> # install pillar >> $ git clone https://github.com/pillar-markup/pillar.git -b v7.4.1 >> $ cd pillar && ./scripts/build.sh && cd .. >> >> # go into the booklet repository and build the pdf >> $ ./pillar/build/pillar build pdf >> >> Although you’ll need a mostly up-to-date latex version (latexmk required, >> plus several other packages, check Pillar’s readme) >> >>> Also, I've never contributed to an open source project; Pharo seems to be >>> a >>> good place to start doing so. I see that most of the documentation, web >>> pages, booklets, etc. are in English so there's the advantage that >>> English >>> is my first language (and I actually paid attention in school :^). I'm >>> also aware, from experience, that Documentation is rarely the first >>> choice >>> for developers to apply their time & enthusiasm… >> >> And it’s super important nevertheless ^^. >> >> Guille > > > > > > -- > Sent from: http://forum.world.st/Pharo-Smalltalk-Developers-f1294837.html > |
|
|
Guillermo Polito wrote
>> El 29 sept 2019, a las 6:13, Brainstorms < > wild.ideas@ > > escribió: >> >> Hi Guillermo, >> >> I forked the uFFI booklet repo, branched your "version2", and revised & >> expanded the introduction section of the first chapter... >> >> I decided that before I got too far, I should submit a pull request for >> just >> that much and get some feedback in case I need trajectory tuning. >> >> Your prose is easy to edit. :^) > > haha, thanks! > I saw it and merged it already :) > >> >> And it looks like my submission promptly broke Travis... Oops. > > I’ll check it locally, probably there is a silly pillar syntax error > somewhere that generates broken latex... > >> I think I know what it is: ==ls -1 /lib/*/libc.so*== probably needs some escape characters. -t -- Sent from: http://forum.world.st/Pharo-Smalltalk-Developers-f1294837.html |
|
|
In reply to this post by Guillermo Polito
Guille can you merge in the master like that I can read it and check without messing everything up.
> On 30 Sep 2019, at 10:35, Guillermo Polito <[hidden email]> wrote: > > > >> El 29 sept 2019, a las 6:13, Brainstorms <[hidden email]> escribió: >> >> Hi Guillermo, >> >> I forked the uFFI booklet repo, branched your "version2", and revised & >> expanded the introduction section of the first chapter... >> >> I decided that before I got too far, I should submit a pull request for just >> that much and get some feedback in case I need trajectory tuning. >> >> Your prose is easy to edit. :^) > > haha, thanks! > I saw it and merged it already :) > >> >> And it looks like my submission promptly broke Travis... Oops. > > I’ll check it locally, probably there is a silly pillar syntax error somewhere that generates broken latex... > >> >> -Ted >> >> >> >> Guillermo Polito wrote >>> Hi Ted, >>> >>> I split this in a separate thread to avoid noise :) >>> >>>> El 23 sept 2019, a las 23:14, Brainstorms < >> >>> wild.ideas@ >> >>> > escribió: >>>> >>>> Guillermo, >>>> >>>> I'm interested in helping, but at this point, I think I'd be most helpful >>>> working at improving documentation (mainly editing) rather than working >>>> on >>>> Pharo code itself. (I'd like to work toward that, though.) >>> >>> I’ve been doing a pass on the structure, and I was thinking on a rough >>> structure as follows: >>> 1) Intro to FFI (callouts, function and library lookup, intro to value >>> marshalling) >>> 2) Marshalling (sending arguments, literal arguments, more on >>> marshalling, basic C types: ints, floats, pointers and how they are >>> transformed to pharo objects and vice-versa…) >>> 3) Complex types: strings, unions, arrays, opaque types >>> 4) Derived types on the Pharo side: How to design nice classes with all >>> this >>> 5) Callbacks >>> 6) Memory management >>> >>> I did already a pass on 1), and I got blocked in 2), though I want to >>> release a version of it this week. >>> >>> If you’re up for it, there are several things we can do: >>> - review the english :) >>> - give feedback on what is missing, what is not understandable, what can >>> be explained better >>> - testing the examples? >>> >>>> >>>> I'm still a newbie with Pharo, but I am a good writer/editor. And I >>>> expect >>>> that working with Pharo documentation would be another means of >>>> increasing >>>> my knowledge of the Pharo ecosystem -- so that's additional incentive for >>>> me. >>> >>> Cool :) >>> >>>> I gather that the PDF books are written using Pillar, which I know >>>> nothing >>>> about. Are there resources & guides for this tool/format that would help >>>> me >>>> learn how to make & edit these kinds of documents? >>> >>> Pillar is a markup syntax (from Pier’s CMS, if you know it). >>> https://github.com/pillar-markup/pillar >>> <https://github.com/pillar-markup/pillar> >>> >>> Pillar comes with a document model, parser and generators to html, pdf >>> (through latex), and others… >>> In Pillar’s readme there are the installation instructions + usage. >>> >>> If you check the travis file in the ffi booklet repository >>> >>> https://github.com/SquareBracketAssociates/Booklet-uFFI/blob/version2/.travis.yml >>> <https://github.com/SquareBracketAssociates/Booklet-uFFI/blob/version2/.travis.yml> >>> >>> You’ll see it is built with pillar 7.4.1. In other words >>> >>> # install pillar >>> $ git clone https://github.com/pillar-markup/pillar.git -b v7.4.1 >>> $ cd pillar && ./scripts/build.sh && cd .. >>> >>> # go into the booklet repository and build the pdf >>> $ ./pillar/build/pillar build pdf >>> >>> Although you’ll need a mostly up-to-date latex version (latexmk required, >>> plus several other packages, check Pillar’s readme) >>> >>>> Also, I've never contributed to an open source project; Pharo seems to be >>>> a >>>> good place to start doing so. I see that most of the documentation, web >>>> pages, booklets, etc. are in English so there's the advantage that >>>> English >>>> is my first language (and I actually paid attention in school :^). I'm >>>> also aware, from experience, that Documentation is rarely the first >>>> choice >>>> for developers to apply their time & enthusiasm… >>> >>> And it’s super important nevertheless ^^. >>> >>> Guille >> >> >> >> >> >> -- >> Sent from: http://forum.world.st/Pharo-Smalltalk-Developers-f1294837.html >> > > |
Re: Pumping FFI documentation
|
|
> El 1 oct 2019, a las 8:45, ducasse <[hidden email]> escribió: > > Guille can you merge in the master like that I can read it and check without messing everything up. Done > > >> On 30 Sep 2019, at 10:35, Guillermo Polito <[hidden email]> wrote: >> >> >> >>> El 29 sept 2019, a las 6:13, Brainstorms <[hidden email]> escribió: >>> >>> Hi Guillermo, >>> >>> I forked the uFFI booklet repo, branched your "version2", and revised & >>> expanded the introduction section of the first chapter... >>> >>> I decided that before I got too far, I should submit a pull request for just >>> that much and get some feedback in case I need trajectory tuning. >>> >>> Your prose is easy to edit. :^) >> >> haha, thanks! >> I saw it and merged it already :) >> >>> >>> And it looks like my submission promptly broke Travis... Oops. >> >> I’ll check it locally, probably there is a silly pillar syntax error somewhere that generates broken latex... >> >>> >>> -Ted >>> >>> >>> >>> Guillermo Polito wrote >>>> Hi Ted, >>>> >>>> I split this in a separate thread to avoid noise :) >>>> >>>>> El 23 sept 2019, a las 23:14, Brainstorms < >>> >>>> wild.ideas@ >>> >>>> > escribió: >>>>> >>>>> Guillermo, >>>>> >>>>> I'm interested in helping, but at this point, I think I'd be most helpful >>>>> working at improving documentation (mainly editing) rather than working >>>>> on >>>>> Pharo code itself. (I'd like to work toward that, though.) >>>> >>>> I’ve been doing a pass on the structure, and I was thinking on a rough >>>> structure as follows: >>>> 1) Intro to FFI (callouts, function and library lookup, intro to value >>>> marshalling) >>>> 2) Marshalling (sending arguments, literal arguments, more on >>>> marshalling, basic C types: ints, floats, pointers and how they are >>>> transformed to pharo objects and vice-versa…) >>>> 3) Complex types: strings, unions, arrays, opaque types >>>> 4) Derived types on the Pharo side: How to design nice classes with all >>>> this >>>> 5) Callbacks >>>> 6) Memory management >>>> >>>> I did already a pass on 1), and I got blocked in 2), though I want to >>>> release a version of it this week. >>>> >>>> If you’re up for it, there are several things we can do: >>>> - review the english :) >>>> - give feedback on what is missing, what is not understandable, what can >>>> be explained better >>>> - testing the examples? >>>> >>>>> >>>>> I'm still a newbie with Pharo, but I am a good writer/editor. And I >>>>> expect >>>>> that working with Pharo documentation would be another means of >>>>> increasing >>>>> my knowledge of the Pharo ecosystem -- so that's additional incentive for >>>>> me. >>>> >>>> Cool :) >>>> >>>>> I gather that the PDF books are written using Pillar, which I know >>>>> nothing >>>>> about. Are there resources & guides for this tool/format that would help >>>>> me >>>>> learn how to make & edit these kinds of documents? >>>> >>>> Pillar is a markup syntax (from Pier’s CMS, if you know it). >>>> https://github.com/pillar-markup/pillar >>>> <https://github.com/pillar-markup/pillar> >>>> >>>> Pillar comes with a document model, parser and generators to html, pdf >>>> (through latex), and others… >>>> In Pillar’s readme there are the installation instructions + usage. >>>> >>>> If you check the travis file in the ffi booklet repository >>>> >>>> https://github.com/SquareBracketAssociates/Booklet-uFFI/blob/version2/.travis.yml >>>> <https://github.com/SquareBracketAssociates/Booklet-uFFI/blob/version2/.travis.yml> >>>> >>>> You’ll see it is built with pillar 7.4.1. In other words >>>> >>>> # install pillar >>>> $ git clone https://github.com/pillar-markup/pillar.git -b v7.4.1 >>>> $ cd pillar && ./scripts/build.sh && cd .. >>>> >>>> # go into the booklet repository and build the pdf >>>> $ ./pillar/build/pillar build pdf >>>> >>>> Although you’ll need a mostly up-to-date latex version (latexmk required, >>>> plus several other packages, check Pillar’s readme) >>>> >>>>> Also, I've never contributed to an open source project; Pharo seems to be >>>>> a >>>>> good place to start doing so. I see that most of the documentation, web >>>>> pages, booklets, etc. are in English so there's the advantage that >>>>> English >>>>> is my first language (and I actually paid attention in school :^). I'm >>>>> also aware, from experience, that Documentation is rarely the first >>>>> choice >>>>> for developers to apply their time & enthusiasm… >>>> >>>> And it’s super important nevertheless ^^. >>>> >>>> Guille >>> >>> >>> >>> >>> >>> -- >>> Sent from: http://forum.world.st/Pharo-Smalltalk-Developers-f1294837.html >>> >> >> > > > |
Re: Pumping FFI documentation
|
|
In reply to this post by tbrunz
Hi Ted,
I think it's the double dash —, which is pillar syntax for strikethrough (https://bintray.com/squarebracketassociates/wip/download_file?file_path=DistributingPillar-wip.pdf). I’ve tried removing it and the pdf compiles neatly. Another solution is to escape the dashes \-\- to get the double dash output in the final text (which in latex renders as a long dash IIRC). I’ve fixed it in the latest commit.
|
|
|
Hi Guillermo,
It did occur to me later that it might be my '--', but I knew you would find it. Glad it's fixed. I'll pull down the PDF and take a look. This does make one wonder if the book-building process could benefit from a 'linter' to catch these things before Pillar starts grinding away. You know, something written in, oh, Pharo maybe..? :^P -Ted Guillermo Polito wrote > Hi Ted, > > I think it's the double dash —, which is pillar syntax for strikethrough > (https://bintray.com/squarebracketassociates/wip/download_file?file_path=DistributingPillar-wip.pdf > <https://bintray.com/squarebracketassociates/wip/download_file?file_path=DistributingPillar-wip.pdf>). > I’ve tried removing it and the pdf compiles neatly. Another solution is to > escape the dashes \-\- to get the double dash output in the final text > (which in latex renders as a long dash IIRC). > > I’ve fixed it in the latest commit. > >> El 30 sept 2019, a las 17:28, Brainstorms < > wild.ideas@ > > escribió: >> >> >> I think I know what it is: >> >> ==ls -1 /lib/*/libc.so*== >> >> probably needs some escape characters. >> >> -t >> >> >> >> >> -- >> Sent from: http://forum.world.st/Pharo-Smalltalk-Developers-f1294837.html >> -- Sent from: http://forum.world.st/Pharo-Smalltalk-Developers-f1294837.html |
|
|
Having the PDF helps... Found another half-dozen typos, which I'll fix
today. I'll also get going on Chapter 2. Quick Pillar question: I notice that the leading ' and " characters are not being rendered correctly. Does this require an escape sequence to get the correct typeset styles? -t -- Sent from: http://forum.world.st/Pharo-Smalltalk-Developers-f1294837.html |
«
Return to Pharo Smalltalk Developers
|
1 view|%1 views
| Free forum by Nabble | Edit this page |