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

Tue Nov 9 06:42:08 UTC 2021

On 08/11/2021 23:53, Chris Johns wrote:
> 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.

How do you get the perma-links?

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

They also have an URL reference, for example:

https://git.rtems.org/rtems-central/tree/spec/c/if/size_t.yml

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

Documentation for types and constants (internal and external) is 
currently not generated. This could be added. In the documentation for a 
type or a constant, we could add links to external pages like this: