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.
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";,
]
?
--
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
