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

[Chris Johns]

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
>>>
>>> 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 and 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 `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 on ftp.rtems.org however the open group site makes that hard
because it is an exception. I am happy to hear about alternative solution?

Chris