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 <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.
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:
See also https://a/b/c.
If you don't like the links, I can also remove them from the document
generator. I still think it is worth to mention exactly the
documentation source which was used to implement the RTEMS version of a
standard interface.
--
embedded brains GmbH
Herr Sebastian HUBER
Dornierstr. 4
82178 Puchheim
Germany
email: sebastian.hu...@embedded-brains.de
phone: +49-89-18 94 741 - 16
fax: +49-89-18 94 741 - 08
Registergericht: Amtsgericht München
Registernummer: HRB 157899
Vertretungsberechtigte Geschäftsführer: Peter Rasmussen, Thomas Dörfler
Unsere Datenschutzerklärung finden Sie hier:
https://embedded-brains.de/datenschutzerklaerung/
_______________________________________________
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel
