I'm pushing this patch set. Eventually we'll want to figure out how to deal with this.
On Tue, Mar 23, 2021 at 9:39 AM Gedare Bloom <ged...@rtems.org> wrote: > > On Tue, Mar 23, 2021 at 9:28 AM Joel Sherrill <j...@rtems.org> wrote: > > > > > > > > On Tue, Mar 23, 2021 at 10:16 AM Gedare Bloom <ged...@rtems.org> wrote: > >> > >> On Mon, Mar 22, 2021 at 3:12 PM Chris Johns <chr...@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@rtems.org > >> http://lists.rtems.org/mailman/listinfo/devel _______________________________________________ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel
