[PATCH rtems-docs v3 1/6] prefixes: Update installation prefix
joel at rtems.org
Tue Mar 23 15:27:43 UTC 2021
On Tue, Mar 23, 2021 at 10:16 AM Gedare Bloom <gedare at rtems.org> wrote:
> On Mon, Mar 22, 2021 at 3:12 PM Chris Johns <chrisj at rtems.org> wrote:
> > On 23/3/21 4:41 am, Gedare Bloom wrote:> I wonder what is your opinion,
> > we bump these tutorials with
> > > every version? And, is the find/replace of the commands the best way
> > > to do this?
> > >
> > > I feel like this topic comes up now and again. Maintaining these
> > > examples is a little fragile.
> > It is fragile and I have in the past invested some time looking for a
> way to
> > automatically manage these version based blocks of documentation however
> > change happen so making it automatic is difficult. Arguments to commands
> > and if there is captured output it needs to change.
> > > @Ida: Thanks for the patches,
> > Yes, thank you. The patches are great.
> > > now we'll need to determine if we want
> > > to bump these examples like this, and whether we should consider a
> > > better way to maintain this stuff in the future.
> > I am open to solutions. A few ideas are:
> > 1. Group commands we consider as stable interfaces and see if the RTEMS
> > can be supplied via a conf variable passed in by waf. This would lower
> > number of changes.
> > 2. Tag version specific blocks with something in a comment. Making a
> change is
> > part of the solution however I find knowing there is a change to make is
> > If we can grep the sources we could see. For example:
> I like tagging.
> > .. rtems-version-block: 5
Texinfo had variables. Looking at Sphinx docs, I see this:
Does that work? Could we have
.. |rtems-version| replace:: 6
This should work in text without doing any magic. It looks like example
and code blocks may need a special block for this to work. I think this
page has a solution to that
This won't help when command line arguments change and things like the
transition from the sis to erc32 BSP will still need work.
> The version number is updated when changed so we can see what needs to be
> > This would be helpful when making releases.
> > 3. Other ideas ...
> A script/tutorial to regenerate these parts could work also. Kind of a
> guide how to update for a new version, and what needs to be
> run/captured as output examples.
> > Chris
> devel mailing list
> devel at rtems.org
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the devel