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

[Chris Johns]

On 15/1/21 6:20 am, Joel Sherrill wrote:
> 
> 
> On Wed, Jan 13, 2021 at 6:26 PM Sebastian Huber
> <sebastian.huber at embedded-brains.de <mailto:sebastian.huber at embedded-brains.de>>
> wrote:
> 
>     On 11/12/2020 01:35, Chris Johns wrote:
> 
>     > On 10/12/20 4:41 pm, Sebastian Huber wrote:
>     >> On 10/12/2020 03:24, Chris Johns wrote:
>     >>
>     >>> On 9/12/20 7:20 pm, Sebastian Huber wrote:
>     >>>> Module:    rtems-docs
>     >>>> Branch:    master
>     >>>> Commit:    d716c79070901195912526c6e49d43defad00bdd
>     >>>> Changeset:
>     >>>>
>     http://git.rtems.org/rtems-docs/commit/?id=d716c79070901195912526c6e49d43defad00bdd
>     <http://git.rtems.org/rtems-docs/commit/?id=d716c79070901195912526c6e49d43defad00bdd>
>     >>>>
>     >>>>
>     >>>> Author:    Sebastian Huber<sebastian.huber at embedded-brains.de
>     <mailto:sebastian.huber at embedded-brains.de>>
>     >>>> Date:      Wed Dec  2 08:17:12 2020 +0100
>     >>>>
>     >>>> c-user: Generate Timer Manager documentation
>     >>>>
>     >>>> The documentation is a consolidation of the comments in Doxygen markup
>     >>>> and the documentation sources in Sphinx markup.  The documentation was
>     >>>> transfered to interface specification items.  The documentation source
>     >>>> files were generated from the items by a script.
>     >>>>
>     >>>> Update #3993.
>     >>>>
>     >>>> ---
>     >>>>
>     >>>>    c-user/timer/directives.rst   | 992
>     ++++++++++++++++++++++++++----------------
>     >>>>    c-user/timer/introduction.rst |  57 ++-
>     >>>>    2 files changed, 674 insertions(+), 375 deletions(-)
>     >>>>
>     >>>> diff --git a/c-user/timer/directives.rst b/c-user/timer/directives.rst
>     >>>> index d9b9877..d65f263 100644
>     >>>> --- a/c-user/timer/directives.rst
>     >>>> +++ b/c-user/timer/directives.rst
>     >>>> @@ -1,463 +1,729 @@
>     >>>>    .. SPDX-License-Identifier: CC-BY-SA-4.0
>     >>>>    +.. Copyright (C) 2020 embedded brains GmbH
>     (http://www.embedded-brains.de <http://www.embedded-brains.de>)
>     >>>>    .. Copyright (C) 1988, 2008 On-Line Applications Research
>     Corporation (OAR)
>     >>>>    +.. 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
>     <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
>     <https://docs.rtems.org/branches/master/eng/req/howto.html>
>     >>>> +
>     >>> We need a solution. I would prefer we resolve this before we add any more
>     >>> instances of these links.
>     >> I understand that cross-document links are a problem, however, these two
>     links
>     >> are in comments and thus don't show up in the generated documents. A link
>     to the
>     >> bug reporting should always point to the latest information since there
>     is only
>     >> one bug reporting procedure in the project at a time. The link to the howto
>     >> could be branch-specific.
>     > Yes I agree. My concern is a change in how master is hosted breaks the links.
>     >
>     >>> Suggestions?
>     >> We could add a script which performs some post processing after creation
>     the of
>     >> the release branches.
>     > What about ....
>     >
>     > https://www.rtems.org/support/bugs.html
>     <https://www.rtems.org/support/bugs.html>
> 
> 
> I can add a page in Drupal with a forced name but am not sure about the support/
> part
> and it looks like Drupal redirect pages are an optional feature which is not
> installed and
> the module may be unsupported. 
> 
> When we did this type of thing before, it was always with Apache itself. That's
> how we
> had rtems.org/PRnnnn <http://rtems.org/PRnnnn> redirect to a specific ticket
> like GCC has. AFAIK This feature 
> was not deemed worthy of inclusion back when the hosting was moved.
> 
> Anyway URL rewriting in Apache is simple with a regular expression in a configuraton
> file. 
>  
> https://httpd.apache.org/docs/2.4/rewrite/remapping.html
> <https://httpd.apache.org/docs/2.4/rewrite/remapping.html>
> 
> All you need to do is convince the admin to add a rule.
> 
> Something like rtems.org/bugs/[567] <http://rtems.org/bugs/[567]> might also be
> nice and shorter. Let bugs with
> no number go to https://devel.rtems.org/wiki/NewTicket
> <https://devel.rtems.org/wiki/NewTicket> which is where "Report a Bug"
> is directed on the right hand side of rtems.org <http://rtems.org>.
> 
> Personally I like using the Apache rewrite engine to make shorter easier to 
> remember URLs.

Good idea. I suggest you ping Amar and ask him to add a rewrite rule.

Chris