[rtems-docs commit] c-user: Generate Timer Manager documentation

[Chris Johns]

On 16/12/20 3:38 am, Sebastian Huber wrote:
> On 15/12/2020 17:26, Gedare Bloom wrote:
>>     [...]
>>
>>     may change and may break. A release with the frozen code will
>>     point to those
>>     same pages for ever and that is broken no matter where the links
>>     are, source,
>>     comments or built and released documentation packages. The links
>>     should either
>>     refer to pages for that release, a link that we declare is stable
>>     or no link but
>>     a reference to chapter etc in a manual.
>>
>> +1
>>
>> We should version cross-doc links, just like internal doc links implicitly are
>> versioned.
> I just would like to emphasize that we are currently talking about links in
> comments which do not show up in the generated documentation for the user.

This understood however why treat comments as something we do not take care of?
We use comments in a number of ways including doxygen so lets not undermine our
user's confidence in them.

>> How that gets done is the key question here.
>>
>> I don't mind adding more of the cross-doc links IF there is a plan in place to
>> sweep all of them at once to fix the versioning. Without a plan to fix the
>> links so they will work right when a release is cut, then I agree with Chris,
>> because it is putting technical debt on him and the release process.
> 
> To which text should I change:
> 
> _AUTOMATICALLY_GENERATED_WARNING = [
>     "This file is part of the RTEMS quality process and was automatically",
>     "generated.  If you find something that needs to be fixed or",
>     "worded better please post a report or patch to an RTEMS mailing list",
>     "or raise a bug report:",
>     "",
> "https://docs.rtems.org/branches/master/user/support/bugs.html",
>     "",
>     "For information on updating and regenerating please refer to:",
>     "",
>     "https://docs.rtems.org/branches/master/eng/req/howto.html",
> ]
> 
> ?

I am with Gedare and prefer we all engage in a solution to cross-links in the
documentation. Maybe that can be a separate topic from the links here and we
separate the issue into cross-links and these links. I am sure these links may
appear in places outside of the documentation.

I suggest we provide a bug page link. The regeneration link is much harder.
Could it be explained in words and we avoid a link ....

  For information on updating and regenerating please refer to the
  How To section of the Software Engineering Manual. The Software
  Engineering Manual is provided as a part of a release. For development
  sources please refer to the online development documentation at
  https://docs.rtems.org.

Chris