[PATCH 1/3] common: Add URLs to manuals

[Chris Johns]

> On 21 Jan 2020, at 4:16 am, Gedare Bloom <gedare at rtems.org> wrote:
> 
> On Sun, Jan 19, 2020 at 10:35 PM Chris Johns <chrisj at rtems.org> wrote:
>> 
>>> On 20/1/20 4:38 pm, Chris Johns wrote:
>>> On 3/1/20 11:31 pm, Sebastian Huber wrote:
>>>> ---
>>>> common/rtemsdomain.py | 14 +++++++++++++-
>>>> 1 file changed, 13 insertions(+), 1 deletion(-)
>>>> 
>>>> diff --git a/common/rtemsdomain.py b/common/rtemsdomain.py
>>>> index 49d0728..018e7ed 100644
>>>> --- a/common/rtemsdomain.py
>>>> +++ b/common/rtemsdomain.py
>>>> @@ -43,7 +43,19 @@ role_url = {
>>>>     "review":                       ("Gerrit Code Review",  "https://review.rtems.org/"),
>>>>     "bugs":                         ("Bugs Database",               "https://devel.rtems.org/wiki/Bugs/"),
>>>>     "gsoc":                         ("Google Summer of Code", "https://devel.rtems.org/wiki/GSoC/"),
>>>> -    "socis":                        ("ESA SOCIS",                   "https://devel.rtems.org/wiki/SOCIS/")
>>>> +    "socis":                        ("ESA SOCIS",                   "https://devel.rtems.org/wiki/SOCIS/"),
>>>> +    "bsp-howto":                    ("RTEMS BSP and Driver Guide",          "https://docs.rtems.org/branches/master/bsp-howto/index.html"),
>>>> +    "cpu-supplement":               ("RTEMS CPU Architecture Supplement",   "https://docs.rtems.org/branches/master/cpu-supplement/index.html"),
>>>> +    "c-user":                       ("RTEMS Classic API Guide",             "https://docs.rtems.org/branches/master/c-user/index.html"),
>>>> +    "develenv":                     ("RTEMS Development Environment Guide", "https://docs.rtems.org/branches/master/develenv/index.html"),
>>>> +    "eclipse":                      ("RTEMS Eclipse Manual",                "https://docs.rtems.org/branches/master/eclipse/index.html"),
>>>> +    "eng":                          ("RTEMS Software Engineering",          "https://docs.rtems.org/branches/master/eng/index.html"),
>>>> +    "filesystem":                   ("RTEMS Filesystem Design Guide",       "https://docs.rtems.org/branches/master/filesystem/index.html"),
>>>> +    "networking":                   ("RTEMS Networking User Manual",        "https://docs.rtems.org/branches/master/networking/index.html"),
>>>> +    "posix-compliance":             ("RTEMS POSIX 1003.1 Compliance Guide", "https://docs.rtems.org/branches/master/posix-compliance/index.html"),
>>>> +    "posix-users":                  ("RTEMS POSIX API Guide",               "https://docs.rtems.org/branches/master/posix-users/index.html"),
>>>> +    "shell":                        ("RTEMS Shell Guide",                   "https://docs.rtems.org/branches/master/shell/index.html"),
>>>> +    "user":                         ("RTEMS User Manual",                   "https://docs.rtems.org/branches/master/user/index.html"),
>>>> }
>>>> 
>>> 
>>> Oh, please do not add references to the online docs. This is rather fragile, ie
>>> branches are broken.
>>> 
>>> I hope it has not been pushed.
>> 
>> It has been. This need to be reverted.
>> 
> I don't quite understand the complaint.

This approach has been raised before. :)

> The links are "working" for now?

Are they? Try editing the Shell manual, build and install, then open a different document you have just built and find one of these links to the shell manual and click on it. You will end up loading the last updated online master build which happens to be last year cause something has broken and I cannot find what is wrong. Your change will not be there. 

Pointing to external documentation this way will never work, the build prefix is not specific to the output format encoding rules. I suspect some special JS is needed how ever what happens with a PDF? The solution needs too support all formats and not just HTML. But the key issue is the URL is not known at build time. 

Finally this mean 5 is broken, it cannot link to the master’s version of the documentation. 

Chris