[PATCH v2] c-user: Document new clock manager directives

[Chris Johns]

On 9/11/21 9:08 am, Joel Sherrill wrote:
> 
> 
> On Mon, Nov 8, 2021, 5:04 PM Chris Johns <chrisj at rtems.org
> <mailto:chrisj at rtems.org>> wrote:
> 
>     On 8/11/21 5:29 pm, Sebastian Huber wrote:
>     > On 25/10/2021 19:50, Sebastian Huber wrote:
>     >> On 19/10/2021 17:25, Sebastian Huber wrote:
>     >>> Add new clock manager directives to get all times provided by the
>     >>> timehands.
>     >>>
>     >>> Update #4527.
>     >>> ---
>     >>> For an updated document to review see:
>     >>>
>     >>> https://ftp.rtems.org/pub/rtems/people/sebh/c-user.pdf
>     <https://ftp.rtems.org/pub/rtems/people/sebh/c-user.pdf>
>     >>>
>     >>> v2: Clarify boot time.
>     >>
>     >> Any comments with respect to the new clock manager directives?
>     >
>     > If I get no objections, I will commit this on Wednesday.
> 
>     We need to discuss and resolve the use of external links to specific pages in
>     our documentation.
> 
>     I have just seen the links to opengroup.org <http://opengroup.org> and
>     cppreference.com <http://cppreference.com> in the patch
>     and was going to comment however a check of the existing documentation shows:
> 
>     $ grep -r cppreference `find . -name \*.rst` | wc -l
>          164
> 
>     $ grep -r opengroup.org <http://opengroup.org> `find . -name \*.rst` | wc -l
>           11
> 
>     It looks like I have missed this happening in the past. I think we need to
>     handle what happens with these external links because it now blocks a 6 release.
> 
>     Deep linking into pages on an external site is at best fragile. I prefer we do
>     not do this because they are:
> 
>     1. Nice but not critical
> 
>     2. Create additional maintenance because someone needs to maintain the links to
>     make sure they are valid for each release. I have no idea how that can be done
>     and as the person handling releases I have no interest in doing this however I
>     have an interest in providing clean and stable releases
> 
>     3. Archived in a release and the referenced web site can and will change their
>     internal structure breaking a long life release. The referenced websites have
>     done this a number of times in the past
> 
>     I am sorry to have to raise this. I did consider us holding an offline copy of
>     cppreference.com <http://cppreference.com> on ftp.rtems.org
>     <http://ftp.rtems.org> however the open group site makes that hard
>     because it is an exception. I am happy to hear about alternative solution?
> 
> 
> The Open Group has perma-links to specific POSIX versions and pages. If we just
> want the latest version of a standard page, that's different.

That would work but in looking at the documentation and the links I still
question the value given the issues it raises. Is the overhead and work worth
what it gives us? Check `clock_settime()` in ...

https://docs.rtems.org/branches/master/c-user/clock/directives.html#rtems-clock-set

I normally just use `man` but I suspect that is just me.

> Give me an example and the goal and I will get some guidance for those.

https://docs.rtems.org/branches/master/c-user/message/directives.html#rtems-message-queue-broadcast

Then a `NULL`. Looking at this the `NULL` is a link but `buffer` is not and that
is confusing but that is the style. If the `NULL` link is broken that would be
frustrating.

Also why not also link `size_t`, `uint32_t` etc?

The fact the link jumps you out to an external site may not be liked by some.
What about those users who are required to be offline?

> Cppreference.com may have a similar permanence but I don't know. We could ask.

Asking would be great.

A halfway point maybe a glossary entry that shows the link and users can see the
jump is external?

Chris