Re: [Pharo-dev] Pumping FFI documentation
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/.travi... <https://github.com/SquareBracketAssociates/Booklet-uFFI/blob/version2/.travi...;
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
El 29 sept 2019, a las 6:13, Brainstorms <wild.ideas@gmail.com> 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/.travi... <https://github.com/SquareBracketAssociates/Booklet-uFFI/blob/version2/.travi...;
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
Hi Ted, I think it's the double dash â, which is pillar syntax for strikethrough (https://bintray.com/squarebracketassociates/wip/download_file?file_path=Dist... <https://bintray.com/squarebracketassociates/wip/download_file?file_path=Dist...>). 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@gmail.com> escribió:
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
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=Dist... <https://bintray.com/squarebracketassociates/wip/download_file?file_path=Dist...;). 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
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 <guillermopolito@gmail.com> wrote:
El 29 sept 2019, a las 6:13, Brainstorms <wild.ideas@gmail.com> 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/.travi... <https://github.com/SquareBracketAssociates/Booklet-uFFI/blob/version2/.travi...;
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
El 1 oct 2019, a las 8:45, ducasse <stepharo@netcourrier.com> 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 <guillermopolito@gmail.com> wrote:
El 29 sept 2019, a las 6:13, Brainstorms <wild.ideas@gmail.com> 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/.travi... <https://github.com/SquareBracketAssociates/Booklet-uFFI/blob/version2/.travi...;
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
participants (3)
-
Brainstorms -
ducasse -
Guillermo Polito