[PATCH rtems-libbsd 0/5] RTEMS LibBSD Documentation

[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.

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 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

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.

Chris