[PATCH rtems-docs v3 1/6] prefixes: Update installation prefix

[Gedare Bloom]

On Tue, Mar 23, 2021 at 9:28 AM Joel Sherrill <joel at rtems.org> wrote:
>
>
>
> 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, should
>> > 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 subtle
>> > change happen so making it automatic is difficult. Arguments to commands change
>> > 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 version
>> > can be supplied via a conf variable passed in by waf. This would lower the
>> > 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 harder.
>> > 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:
>
> https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#substitutions
>
> 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
>
>  https://stackoverflow.com/questions/42158111/variable-substitution-not-working-properly-in-sphinx
>
> This won't help when command line arguments change and things like the
> transition from the sis to erc32 BSP will still need work.
>
It also doesn't address that example output changes with each version.
That's the bigger problem here.

>> > The version number is updated when changed so we can see what needs to be done.
>> > 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
>> http://lists.rtems.org/mailman/listinfo/devel