On 9/11/21 9:08 am, Joel Sherrill wrote: > > > On Mon, Nov 8, 2021, 5:04 PM Chris Johns <chr...@rtems.org > <mailto:chr...@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 _______________________________________________ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel