Re: [PATCH rtems-docs v3 1/6] prefixes: Update installation prefix
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 wrote: > > On Tue, Mar 23, 2021 at 9:28 AM Joel Sherrill wrote: > > > > > > > > On Tue, Mar 23, 2021 at 10:16 AM Gedare Bloom wrote: > >> > >> On Mon, Mar 22, 2021 at 3:12 PM Chris Johns 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
Re: [PATCH rtems-docs v3 1/6] prefixes: Update installation prefix
On Tue, Mar 23, 2021 at 9:28 AM Joel Sherrill wrote: > > > > On Tue, Mar 23, 2021 at 10:16 AM Gedare Bloom wrote: >> >> On Mon, Mar 22, 2021 at 3:12 PM Chris Johns 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
Re: [PATCH rtems-docs v3 1/6] prefixes: Update installation prefix
On Tue, Mar 23, 2021 at 10:16 AM Gedare Bloom wrote: > On Mon, Mar 22, 2021 at 3:12 PM Chris Johns 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. > 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
Re: [PATCH rtems-docs v3 1/6] prefixes: Update installation prefix
On Mon, Mar 22, 2021 at 3:12 PM Chris Johns 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 > > 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
Re: [PATCH rtems-docs v3 1/6] prefixes: Update installation prefix
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: .. rtems-version-block: 5 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 ... Chris ___ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel
Re: [PATCH rtems-docs v3 1/6] prefixes: Update installation prefix
Hi Chris, 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. @Ida: Thanks for the patches, 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. Gedare On Sat, Mar 20, 2021 at 12:55 PM Ida Delphine wrote: > > --- > user/start/prefixes.rst | 8 > 1 file changed, 4 insertions(+), 4 deletions(-) > > diff --git a/user/start/prefixes.rst b/user/start/prefixes.rst > index 67255d0..826ce85 100644 > --- a/user/start/prefixes.rst > +++ b/user/start/prefixes.rst > @@ -40,7 +40,7 @@ applications and systems. > You build and install the tool suite with the :ref:`RTEMS Source Builder > (RSB) > `. By default, the RSB will start the prefix path with a host operating > system specific path plus :file:`rtems`, and the RTEMS version, e.g. > -:file:`/opt/rtems/5` on Linux, and :file:`/usr/local/rtems/5` on FreeBSD and > +:file:`/opt/rtems/6` on Linux, and :file:`/usr/local/rtems/6` on FreeBSD and > macOS. Placing the RTEMS version number in the path lets you manage and > migrate RTEMS versions as they are released. > > @@ -50,10 +50,10 @@ make sure that your normal user has sufficient privileges > to create files and > directories under the prefix. For example, you can create a directory > :file:`/opt/rtems` and give it to a developer group with read, write, and > execute permissions. Alternatively, you can choose a prefix in your home > -directory, e.g. :file:`$HOME/rtems/5` or with a project-specific component > -:file:`$HOME/project-x/rtems/5`. For more ideas, see the :ref:`project > +directory, e.g. :file:`$HOME/rtems/6` or with a project-specific component > +:file:`$HOME/project-x/rtems/6`. For more ideas, see the :ref:`project > sandboxing ` section. In this quick start chapter, we > will > -choose :file:`$HOME/quick-start/rtems/5` for the RTEMS tool suite prefix. > +choose :file:`$HOME/quick-start/rtems/6` for the RTEMS tool suite prefix. > > .. warning:: > > -- > 2.25.1 > > ___ > 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
