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

[Joel Sherrill]

On Mon, Nov 8, 2021, 5:04 PM Chris Johns <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
> >>>
> >>> 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?
>

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.

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

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

--joel

>
> Chris
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel
>