Re: The NuttX Handbook
https://www.amazon.com/MicroC-OS-II-Kernel-CD-ROM/dp/1578201039 Wow, never heard about that book but just looking at the ToC makes me want to get one :-) The original uC/OS I book published in 1992 was the one that really established uC/OS and led to Micrium. I think that is this book: https://www.amazon.com/gp/product/0132429675 but I am not sure. Might be https://www.amazon.com/MC-Real-Time-Kernel-Jean-Labrosse/dp/0879304448. I have never had a copy, but I understand that it had the whole uC/OS source code in the book. It was still proprietary but everyone used it because the source code was available.
Re: The NuttX Handbook
On Mon, May 15, 2023 at 4:23 AM Brennan Ashton wrote: > I suspect we need to get our documentation ducks in order before that > outside help will be very useful. I agree that the aspiration should be > something like the uC/OS II book which Greg mentioned, > while dated at this point is very well written and highly technical > reference. This was one of my first OS reference books many years > ago. But also this book was written by the author of the OS. > > https://www.amazon.com/MicroC-OS-II-Kernel-CD-ROM/dp/1578201039 Wow, never heard about that book but just looking at the ToC makes me want to get one :-) > We have a long way to go, but we can get there :) Small steps towards big dreams :-) Thank you Brennan for making this first step a reality :-) -- CeDeROM, SQ7MHZ, http://www.tomek.cedro.info
Re: The NuttX Handbook
> > The first author that comes to mind, just off the top of my head, is Derek > Molloy, the author of books like Exploring Raspberry Pi [1] and Exploring > BeagleBone [2]. Both of these are about embedded systems. Both of these > include tutorials not only in electronics (how to use FET transistors, for > example) and embedded systems (how to use GPIOs and not blow up your board) > but also higher level topics in Linux, since both boards run Linux distros > by default. (Side note: I would love to see these boards run NuttX!!) So > this author is no stranger to electronics, embedded, coding, and POSIX > systems. > > It might sound like a fabulous idea but unfortunately I have no idea how > one would reach this author to ask!! If someone knows, please do it!! > > > Cheers > Nathan I suspect we need to get our documentation ducks in order before that outside help will be very useful. I agree that the aspiration should be something like the uC/OS II book which Greg mentioned, while dated at this point is very well written and highly technical reference. This was one of my first OS reference books many years ago. But also this book was written by the author of the OS. https://www.amazon.com/MicroC-OS-II-Kernel-CD-ROM/dp/1578201039 There are great examples recently of books that I think fit this bill and have continued to be developed in the public forum. One great example is The Rust Book https://doc.rust-lang.org/book/ The main authors are major contributors to the Rust project, but many others have contributed and continue to contribute to that. We have a long way to go, but we can get there :) --Brennan
Re: The NuttX Handbook
On Sun, May 14, 2023 at 7:44 PM Gregory Nutt wrote: > > > On 5/14/23, Brennan Ashton wrote: > >> Before I do more work to wire this up, please let me know if this pdf > >> I have attached here seems like a reasonable start for people > >> https://github.com/apache/nuttx/issues/9095#issuecomment-1547008998 > >> > >> It is basically the same content on the website, so missing > >> information is out of scope of this change, > >> but I don't want to fix some compatibility issues here unless people > >> actually think this is of value. > >> > Over the years, there have been several people with the dream of writing > a commercial, NuttX book in the spirit of the famous uC/OS book. There > were even a few starts but all gave up when the magnitude of the effort > sunk in. > > But this looks like a good begubbubg. It looks like a book. It does look very good for starters! Of course there are a lot of omissions right now but that is OK right now because it is generated from Documentation in the repo, which contains a lot of omissions... I think that having the docs in the form of a book or PDF allows us to see the structure of the documentation more easily and therefore we can write better documentation. I recommend to keep it as automatically generated from Documentation in the repo because that will reduce duplication of effort. When we improve Documentation, we will automatically improve the website and the PDF book. There are many "easy" areas to fix and improve. For example, the section of supported architectures lists only a few while in truth we support a lot more. But as Brennan said, we're not talking about omissions right now. :-) How much additional effort would it take to develop a book (like an > O'Reilly book) or a free eBook on Amazon or Google Books? That would be a neat idea! Maybe we could reach out to some professional technical writers and find out if they'd like to take on the project and publish a professional (for sale) book. The first author that comes to mind, just off the top of my head, is Derek Molloy, the author of books like Exploring Raspberry Pi [1] and Exploring BeagleBone [2]. Both of these are about embedded systems. Both of these include tutorials not only in electronics (how to use FET transistors, for example) and embedded systems (how to use GPIOs and not blow up your board) but also higher level topics in Linux, since both boards run Linux distros by default. (Side note: I would love to see these boards run NuttX!!) So this author is no stranger to electronics, embedded, coding, and POSIX systems. It might sound like a fabulous idea but unfortunately I have no idea how one would reach this author to ask!! If someone knows, please do it!! [1] https://a.co/d/5S3Etz0 [2] https://a.co/d/avmNiH7 Cheers Nathan
Re: The NuttX Handbook
Here goes the ePub format test build: https://github.com/apache/nuttx/files/11473321/NuttX.epub.zip I had to zip it for GH to accept the file, please unzip after download. You can use your favorite e-book reader (even Kindle) or Calibre desktop application to open it: https://github.com/kovidgoyal/calibre -- CeDeROM, SQ7MHZ, http://www.tomek.cedro.info
Re: The NuttX Handbook
On Mon, May 15, 2023 at 1:44 AM Gregory Nutt wrote: > Over the years, there have been several people with the dream of writing > a commercial, NuttX book in the spirit of the famous uC/OS book. There > were even a few starts but all gave up when the magnitude of the effort > sunk in. > > But this looks like a good begubbubg. It looks like a book. This is just Sphinx output to PDF in addition to HTML that I was talking about some time ago giving Kivy docs as an example :-) > How much additional effort would it take to develop a book (like an > O'Reilly book) or a free eBook on Amazon or Google Books? Well this is in fact the current nuttx.git/Documentation. It needs to be cleaned up and developed to become "the book" we want. Then it can be published not only on the project website but also web stores for free and maybe for purchase in order to support the project development :-) Sphinx offers following output formats: html (standalone, directories, singlepage), pickle, json, html help, qt help, dev help, ePub (!!), LaTeX/PDF (!!), text, man, texinfo, info, gettext, xml. Virtually anything can be created and/or converted to. PDF and ePub seems most common online book formats nowadays. > To bad we don't have a technical writer on the team. I will try to help in this area. But first I need to get really good familiarization myself with the details (this will take some time sorry). Any technical writer would have to go along that path too :-) I am thinking about step-by-step introduction based on real world examples that would provide recipes ready for use for people like me :-P I really love to work with PDF Handbooks. Thank you Brennan for making the first step a reality!! :-) -- CeDeROM, SQ7MHZ, http://www.tomek.cedro.info
Re: The NuttX Handbook
On 5/14/23, Brennan Ashton wrote: Before I do more work to wire this up, please let me know if this pdf I have attached here seems like a reasonable start for people https://github.com/apache/nuttx/issues/9095#issuecomment-1547008998 It is basically the same content on the website, so missing information is out of scope of this change, but I don't want to fix some compatibility issues here unless people actually think this is of value. Over the years, there have been several people with the dream of writing a commercial, NuttX book in the spirit of the famous uC/OS book. There were even a few starts but all gave up when the magnitude of the effort sunk in. But this looks like a good begubbubg. It looks like a book. How much additional effort would it take to develop a book (like an O'Reilly book) or a free eBook on Amazon or Google Books? To bad we don't have a technical writer on the team.
Re: The NuttX Handbook
On 5/14/23, Brennan Ashton wrote: sic > Before I do more work to wire this up, please let me know if this pdf > I have attached here seems like a reasonable start for people > https://github.com/apache/nuttx/issues/9095#issuecomment-1547008998 > > It is basically the same content on the website, so missing > information is out of scope of this change, > but I don't want to fix some compatibility issues here unless people > actually think this is of value. > Looks promising!!! Some suggestions: Include Apache Sofware Foundation logo in the first page. Also in the first page instead of just "NuttX" -> The NuttX RTOS Documentation BR, Alan
Re: The NuttX Handbook
On Sun, May 14, 2023 at 11:58 PM Brennan Ashton wrote: > Before I do more work to wire this up, please let me know if this pdf > I have attached here seems like a reasonable start for people > https://github.com/apache/nuttx/issues/9095#issuecomment-1547008998 > > It is basically the same content on the website, so missing > information is out of scope of this change, > but I don't want to fix some compatibility issues here unless people > actually think this is of value. Looks awesome! Congratulation Brennan :-) We could create a tar.gz packages for each release along with full pdf documentation. Then save it in various places and we are ready for zombie apocalypse! :-) I did put my thought on the GH Issue, below summary of ideas: https://github.com/apache/nuttx/issues/9095 Some tweaking that comes to my mind at first look: * headers, introduction, etc. * re-formatting long tables that does not fit into a single page can be converted to a long list, etc * moving long parts (i.e. Apache License) to Appendix section. * Table of Contents tree embedded into PDF. * clickable table of contents. * images/charts reference index. * making PDF as small as possible. Please let me know how can I help? :-) -- CeDeROM, SQ7MHZ, http://www.tomek.cedro.info
Re: The NuttX Handbook
On Tue, Apr 25, 2023 at 8:46 AM Brennan Ashton wrote: > > > > On Tue, Apr 25, 2023, 3:18 PM Gregory Nutt wrote: >> >> >> > Thanks Alan! This is why I was a bit surprised why the documentation >> > is not direct part of the source code (i.e. documentation of the >> > file/module/function right in that file/module/function). Kivy does >> > that, it helps understanding the code, allows easy online/pdf >> > documentation out of it, and most important keeps documentation >> > coherent and up to date with the code! >> > >> > It could be easier to maintain / keep things coherent.. this can be >> > also done with Sphinx that we already use.. what do you >> >> The current coding >> standardhttps://cwiki.apache.org/confluence/display/NUTTX/Coding+Standard#fileorganization >> forbids documentation tags in the code, but that could change. > > > I think you mean this page in the docs :) > https://nuttx.apache.org/docs/latest/contributing/coding_style.html?highlight=deoxygen > >> >> My experience with using Deoxygen on large, projects has been >> disastrous. People don't always maintain the tags to the documentation >> was wrong and so the auto-generated documentation was not >> trust-worthy. So you always end up looking at the code anyway. There >> is nothing in the auto-generated code that is not in the the files so >> there is no real value added (there would be if you could trust it). >> >> Also, minor errors in the tags cause a lot of CI failures. A couple per >> week. >> >> I suppose if documentation tags were added to all files and were all of >> the highest quality, it would be a good thing. That that would be an >> enormous job and ongoing maintained of the documentation tags would be a >> problem: Most people won't change them or put in useless, low value >> tags. Much like PR comments. Or comments and documentation in general. >> >> If we could do it right, then +1 with a significant commitment of time >> and effort. If we would do only a half-assed job, then -1. > > > I _very_ much agree. I have very rarely found doxygen to be useful and > usually just results in unhelpful boilerplate to make the tool happy and > generates some html that no one will ever look at again. It is usually much > better when someone spends the time to actually document the interfaces and > the why behind them (like man pages) we already have a section in the docs > for interfaces and it would be great as people extend and adapt them to > continue keeping these up to date. > > Additionally from this discussion I have opened two tickets from this thread. > > * Generate and publish the PDF alongside the html docs > https://github.com/apache/nuttx/issues/9095 > * A tracking ticket to unify more of the docs. > https://github.com/apache/nuttx/issues/9094 > > I will start in on both once I return from holiday and have time in front of > a real computer again. > > --Brennan Before I do more work to wire this up, please let me know if this pdf I have attached here seems like a reasonable start for people https://github.com/apache/nuttx/issues/9095#issuecomment-1547008998 It is basically the same content on the website, so missing information is out of scope of this change, but I don't want to fix some compatibility issues here unless people actually think this is of value. --Brennan
Re: www/contributors PMC, IPMC, PPMC.
On Sun, May 14, 2023 at 10:32 PM Brennan Ashton wrote: > On Sun, May 14, 2023, 1:12 PM Tomek CEDRO wrote: > > One last question: how is the website updated? :-P > > By running publish.sh ? > > Is it safe to run? > > This is handled by CI. I just put up a PR to fix the publish issue > triggered by your git user.name. Once that merges this will publish. Thank you Brennan :-) -- CeDeROM, SQ7MHZ, http://www.tomek.cedro.info
Re: www/contributors PMC, IPMC, PPMC.
On Sun, May 14, 2023, 1:12 PM Tomek CEDRO wrote: > One last question: how is the website updated? :-P > > By running publish.sh ? > > Is it safe to run? > This is handled by CI. I just put up a PR to fix the publish issue triggered by your git user.name. Once that merges this will publish. --brennan
Re: www/contributors PMC, IPMC, PPMC.
One last question: how is the website updated? :-P By running publish.sh ? Is it safe to run? I have no experience with ruby gems.. not all packages from Gemfile are available out of the box on FreeBSD and I failed miserably to install them on a local user account.. but I could create a local Linux VM in order to run the script if necessary.. just wanted to ask before I mess up anything :-) :-) Anyways in case of any updates on the website I am here to help :-) Thank you for you support folks :-) Tomek -- CeDeROM, SQ7MHZ, http://www.tomek.cedro.info
Re: www/contributors PMC, IPMC, PPMC.
On Sun, May 14, 2023 at 9:25 PM Alan C. Assis wrote: > Please include a new commit in this PR to include your name. Thanks Alan! :-) I am already here line 164? :-) Diff wrapped that, change was added in last PR, currently we only update PPMC -> PMC :-) -- CeDeROM, SQ7MHZ, http://www.tomek.cedro.info
Re: www/contributors PMC, IPMC, PPMC.
Please include a new commit in this PR to include your name. BR, Alan On 5/14/23, Tomek CEDRO wrote: > Updated version, please verify :-) > > https://github.com/apache/nuttx-website/pull/93 > > -- > CeDeROM, SQ7MHZ, http://www.tomek.cedro.info >
Re: www/contributors PMC, IPMC, PPMC.
Updated version, please verify :-) https://github.com/apache/nuttx-website/pull/93 -- CeDeROM, SQ7MHZ, http://www.tomek.cedro.info
Re: www/contributors PMC, IPMC, PPMC.
On 5/14/23, Gregory Nutt wrote: > On 5/14/2023 12:45 PM, Tomek CEDRO wrote: >> Hello world :-) >> >> I have updated the www with social media section in the Community page >> :-) >> >> Also I have humbly added myself to the contributors list. I was not >> sure what *PMC to use, so I sipmly used PMC. >> >> As project has graduated, I can update all PMC members with the PMC >> status. The question is if we want to keep IPMC and PPMC roles to >> retain history (preferred) or simply replace IPMC/PPMC with PMC? >> >> Here is the PR: https://github.com/apache/nuttx-website/pull/92 >> >> Any hints welcome :-) >> Tomek >> > PPMC is the podling PMC. We are no longer a incubating "podling", we > are a TLP (top-level project). So any occurrences of PPMC should be > replacement with PMC. Same thing, just promoted to TDP. > > IPMC is something different. You need to retain all references to the > IPMC. That is the incubator PMC that is in charge of all of the PPMCs. > So some people who were our mentors are in the IPMC and were also the > PPMC (which is now the PMC). > My fault Greg, I already merged it. Tomek, please send a fix and a commit adding you to the list. BR, Alan
Re: www/contributors PMC, IPMC, PPMC.
On 5/14/23, Tomek CEDRO wrote: > Hello world :-) > > I have updated the www with social media section in the Community page :-) > > Also I have humbly added myself to the contributors list. I was not > sure what *PMC to use, so I sipmly used PMC. > > As project has graduated, I can update all PMC members with the PMC > status. The question is if we want to keep IPMC and PPMC roles to > retain history (preferred) or simply replace IPMC/PPMC with PMC? > > Here is the PR: https://github.com/apache/nuttx-website/pull/92 > > Any hints welcome :-) I just merged it. But I think you didn't include yourself in the file, please double check. Probably you did it as another commit that wasn't in the PR. BR, Alan
Re: www/contributors PMC, IPMC, PPMC.
On 5/14/2023 12:45 PM, Tomek CEDRO wrote: Hello world :-) I have updated the www with social media section in the Community page :-) Also I have humbly added myself to the contributors list. I was not sure what *PMC to use, so I sipmly used PMC. As project has graduated, I can update all PMC members with the PMC status. The question is if we want to keep IPMC and PPMC roles to retain history (preferred) or simply replace IPMC/PPMC with PMC? Here is the PR: https://github.com/apache/nuttx-website/pull/92 Any hints welcome :-) Tomek PPMC is the podling PMC. We are no longer a incubating "podling", we are a TLP (top-level project). So any occurrences of PPMC should be replacement with PMC. Same thing, just promoted to TDP. IPMC is something different. You need to retain all references to the IPMC. That is the incubator PMC that is in charge of all of the PPMCs. So some people who were our mentors are in the IPMC and were also the PPMC (which is now the PMC).
www/contributors PMC, IPMC, PPMC.
Hello world :-) I have updated the www with social media section in the Community page :-) Also I have humbly added myself to the contributors list. I was not sure what *PMC to use, so I sipmly used PMC. As project has graduated, I can update all PMC members with the PMC status. The question is if we want to keep IPMC and PPMC roles to retain history (preferred) or simply replace IPMC/PPMC with PMC? Here is the PR: https://github.com/apache/nuttx-website/pull/92 Any hints welcome :-) Tomek -- CeDeROM, SQ7MHZ, http://www.tomek.cedro.info
