On Wed, Aug 4, 2021 at 9:05 AM Christian MAUDERER <christian.maude...@embedded-brains.de> wrote: > > Hello Gedare, > > Am 04.08.21 um 16:55 schrieb Gedare Bloom: > > On Wed, Aug 4, 2021 at 4:18 AM Christian MAUDERER > > <christian.maude...@embedded-brains.de> wrote: > >> > >> Hello Chris, > >> > >> Am 04.08.21 um 11:17 schrieb Chris Johns: > >>> > >>> > >>> On 4/8/21 6:34 pm, Christian MAUDERER wrote: > >>>> Hello Chris, > >>>> > >>>> Am 04.08.21 um 09:28 schrieb Chris Johns: > >>>>> On 3/8/21 5:00 pm, Christian MAUDERER wrote: > >>>>>> Hello, > >>>>>> > >>>>>> Am 03.08.21 um 04:07 schrieb Chris Johns: > >>>>>>> On 3/8/21 3:24 am, Sebastian Huber wrote: > >>>>>>>> On 02/08/2021 18:37, Vijay Kumar Banerjee wrote: > >>>>>>>>> I think there should be a high-level user manual subsection for > >>>>>>>>> networking that describes how the selection of the network stack > >>>>>>>>> works. We can then add another subsection about lwip since legacy > >>>>>>>>> already has one, and libbsd is getting added now. > >>>>>>>> > >>>>>>>> This sounds like a good approach. > >>>>>>>> > >>>>>>> > >>>>>>> I agree. > >>>>>>> > >>>>>>> Chris > >>>>>> > >>>>>> Just so that we are all on the same page: > >>>>>> > >>>>>> That would be a number of new subsections in > >>>>>> https://docs.rtems.org/branches/master/user/index.html: > >>>>>> > >>>>>> - 15. Selecting a Network Stack > >>>>>> - 16. Add-on: libbsd Stack > >>>>>> - 17. Add-on: lwIP > >>>>>> - 18. Add-on: Legacy Network Stack > >>>>>> > >>>>>> Or was it meant to be only a section > >>>>> > >>>>> I think a single section so all things networking are grouped. > >>>> > >>>> That will result in either a deep nesting for the chapters or in very > >>>> hard to > >>>> organize information because two levels are used up already. > >>>> > >>>> For example the current legacy network manual has a > >>>> > >>>> 5.3.1. Additional include files > >>>> > >>>> If we make one "networking" group, that would be > >>>> > >>>> 15. Networking > >>>> 15.3 Legacy Network Stack > >>>> 15.3.5 Using Networking in an RTEMS application > >>>> 15.3.5.3 Initialization > >>>> 15.3.5.3.1 Additional include files > >>>> > >>>> And please also note: I think we should see libbsd more as an Add-on > >>>> package and > >>>> less as a pure network stack. > >>> > >>> Yes this is true and if your top level is LibBSD you do not see > >>> networking and > >>> then networking becomes confusing if spread out in pieces. What would > >>> LibBSD and > >>> Legacy Networking mean if you are new RTEMS? Is Legacy networking some > >>> form of > >>> old embedded realtime protocol we support? :) > >>> > >>> Maybe Networking is about the history, features and options available in > >>> each > >>> package (Selection) and the LibBSD part is a link to the networking > >>> section of > >>> that package? This would mean the lwIP and Legacy network stack is still > >>> under > >>> Networking. > >> > >> Hm. You are right that we have to somehow make it clear what features > >> can be provided by the libraries. > >> > >>> > >>> Does "Additional includes" etc need to be a numbered section? Why not > >>> just make > >>> a heading in the block without it being a section? > >> > >> It was more or less an example that I just took from the current legacy > >> networking manual. I think that manual should be about at the same > >> location and I don't think that anyone wants to do a detailed re-write. > >> So most likely we will just move the levels down. > >> > >>> > >>>> It provides a lot more than just networking. It > >>>> has USB, it can add HDMI (on beagle for example), it includes an OpenSSL > >>>> implementation, ... > >>> > >>> Yes and if you look at the top level you could see something like: > >>> > >>> 9 Networking > >>> 10 USB > >>> 11 Graphics > >>> 12 FreeBSD On RTEMS > > +1 > > > >>> > >>> The user manual has clear top level sections and I would like it to stay > >>> this > >>> way. But yes I understand it is hard to get the breakdown right and it > >>> may take > >>> a couple more loops until we have something that is clear. > >> > >> Hm. That would mean that we split up the libbsd documentation to > >> multiple sections (at least networking and USB). Where can we put common > >> parts like "how to init libbsd"? > >> > >> We also have multiple options in every section. For example OpenSSL can > >> be provided by libbsd or by OpenSSL / LibreSSL / *SSL. Could be > >> difficult for a user to find out how and which libs he can combine to > >> get what he wants. For example some user could start with lwIP for > >> networking and then later wants to add USB and SD/MMC and notes that in > >> that case it would have been a better choice to use libbsd for > >> networking in that case too. > >> > >> We could add a chapter "Selecting Add-Ons" or "Selecting Libraries" with > >> a short description of the libs and when they are alternatives or when > > > > I'd like this as well. A library of libraries :) [technically, an > > index of libraries] > > > >> they complement each other. Then we can either add the manual of the > >> libs or Add-Ons as subsections (disadvantage: deep nesting) or we can > >> add them with some common prefix so that a user knows that he maybe > >> should first look into the "Selecting <Prefix>". > > +1 > > > >> > > > > My preference would be to leave the legacy doc where it is, > > Just a comment for that point: I know that the doc has been moved around > a bit. But I think we should try to get all similar options onto the > same "level". Otherwise if a user searches for "How to do networking > with RTEMS" and he finds https://docs.rtems.org/ the only manual with > "Networking" is the legacy stack. If it is on the same page (level, > hirarchie, ...) like the headline "libbsd Networking and other cool > stuff" or "lwIP", a user instantly can see that there is more than one > option. >
That's a good point, but I want to keep the legacy stack separate from the rest of the documentation to make it simpler to deprecate/obsolete it. I don't see value in moving it, just to kill it in the next release. AFAIK, we will strongly discourage anyone from using it in rtems-6, and I'd like to kill it off moving forward once we feel confident that lwIP is feasible for us to maintain. Your point about marketing is well-taken though. > Of course, I'm open for discussion regarding that point. > > Best regards > > Christian > > > and add a > > new libbsd section in the user manual, and cross-reference to it from > > other sections with clear high-level names (like Networking, USB, > > etc.) That is much the same way as we treated the RSB documentation. > > We need to refer to the libbsd too much for it to be in a separate > > manual, since cross-doc linking doesn't work, but we also should try > > not to split up the libbsd content and spread it around too much. I > > think that might be what Chris meant by his listing, with 12. FreeBSD > > on RTEMS. > > > > I'm open to suggestions though. > > > > Gedare > > > >> Best regards > >> > >> Christian > >> > >>> > >>> Chris > >>> > >> > >> -- > >> -------------------------------------------- > >> embedded brains GmbH > >> Herr Christian MAUDERER > >> Dornierstr. 4 > >> 82178 Puchheim > >> Germany > >> email: christian.maude...@embedded-brains.de > >> phone: +49-89-18 94 741 - 18 > >> fax: +49-89-18 94 741 - 08 > >> > >> Registergericht: Amtsgericht München > >> Registernummer: HRB 157899 > >> Vertretungsberechtigte Geschäftsführer: Peter Rasmussen, Thomas Dörfler > >> Unsere Datenschutzerklärung finden Sie hier: > >> https://embedded-brains.de/datenschutzerklaerung/ > > -- > -------------------------------------------- > embedded brains GmbH > Herr Christian MAUDERER > Dornierstr. 4 > 82178 Puchheim > Germany > email: christian.maude...@embedded-brains.de > phone: +49-89-18 94 741 - 18 > fax: +49-89-18 94 741 - 08 > > Registergericht: Amtsgericht München > Registernummer: HRB 157899 > Vertretungsberechtigte Geschäftsführer: Peter Rasmussen, Thomas Dörfler > Unsere Datenschutzerklärung finden Sie hier: > https://embedded-brains.de/datenschutzerklaerung/ _______________________________________________ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel
