<div dir="ltr"><div dir="ltr"><br></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Tue, Mar 23, 2021 at 10:16 AM Gedare Bloom <<a href="mailto:gedare@rtems.org">gedare@rtems.org</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">On Mon, Mar 22, 2021 at 3:12 PM Chris Johns <<a href="mailto:chrisj@rtems.org" target="_blank">chrisj@rtems.org</a>> wrote:<br>
><br>
> On 23/3/21 4:41 am, Gedare Bloom wrote:> I wonder what is your opinion, should<br>
> we bump these tutorials with<br>
> > every version? And, is the find/replace of the commands the best way<br>
> > to do this?<br>
> ><br>
> > I feel like this topic comes up now and again. Maintaining these<br>
> > examples is a little fragile.<br>
><br>
> It is fragile and I have in the past invested some time looking for a way to<br>
> automatically manage these version based blocks of documentation however subtle<br>
> change happen so making it automatic is difficult. Arguments to commands change<br>
> and if there is captured output it needs to change.<br>
><br>
> > @Ida: Thanks for the patches,<br>
><br>
> Yes, thank you. The patches are great.<br>
><br>
> > now we'll need to determine if we want<br>
> > to bump these examples like this, and whether we should consider a<br>
> > better way to maintain this stuff in the future.<br>
><br>
> I am open to solutions. A few ideas are:<br>
><br>
> 1. Group commands we consider as stable interfaces and see if the RTEMS version<br>
> can be supplied via a conf variable passed in by waf. This would lower the<br>
> number of changes.<br>
><br>
> 2. Tag version specific blocks with something in a comment. Making a change is<br>
> part of the solution however I find knowing there is a change to make is harder.<br>
> If we can grep the sources we could see. For example:<br>
><br>
I like tagging.<br>
<br>
> .. rtems-version-block: 5<br>
><br></blockquote><div><br></div><div>Texinfo had variables. Looking at Sphinx docs, I see this:<br><br><a href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#substitutions">https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#substitutions</a><br></div><div><br></div><div>Does that work? Could we have </div><div><br></div><div>.. |rtems-version| replace:: 6<br><br></div><div>This should work in text without doing any magic. It looks like example </div><div>and code blocks may need a special block for this to work. I think this </div><div>page has a solution to that<br></div><div><br></div><div> <a href="https://stackoverflow.com/questions/42158111/variable-substitution-not-working-properly-in-sphinx">https://stackoverflow.com/questions/42158111/variable-substitution-not-working-properly-in-sphinx</a></div><div><br></div><div>This won't help when command line arguments change and things like the </div><div>transition from the sis to erc32 BSP will still need work.</div><div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
> The version number is updated when changed so we can see what needs to be done.<br>
> This would be helpful when making releases.<br>
><br>
> 3. Other ideas ...<br>
><br>
A script/tutorial to regenerate these parts could work also. Kind of a<br>
guide how to update for a new version, and what needs to be<br>
run/captured as output examples.<br>
<br>
> Chris<br>
_______________________________________________<br>
devel mailing list<br>
<a href="mailto:devel@rtems.org" target="_blank">devel@rtems.org</a><br>
<a href="http://lists.rtems.org/mailman/listinfo/devel" rel="noreferrer" target="_blank">http://lists.rtems.org/mailman/listinfo/devel</a><br>
</blockquote></div></div>