| Message ID | 20220711171439.1657280-5-trini@konsulko.com |
|---|---|
| State | Superseded |
| Delegated to: | Heinrich Schuchardt |
| Headers | show |
| Series | [1/7] doc: Migrate CodingStyle wiki page to Sphinx | expand |
On 7/11/22 19:14, Tom Rini wrote: > - Remove some missed wiki markup, and escape a "\n" correctly. > - Use gender-neutral language to refer to the user, consistently. > > Cc: Claudius Heine <ch@denx.de> > Cc: Heinrich Schuchardt <xypron.glpk@gmx.de> > Signed-off-by: Tom Rini <trini@konsulko.com> > --- > Changes in v2: > - None > --- > doc/develop/designprinciples.rst | 24 ++++++++++++------------ > 1 file changed, 12 insertions(+), 12 deletions(-) > > diff --git a/doc/develop/designprinciples.rst b/doc/develop/designprinciples.rst > index 43aeb5dacf5f..e5e12dca79f5 100644 > --- a/doc/develop/designprinciples.rst > +++ b/doc/develop/designprinciples.rst > @@ -28,15 +28,15 @@ millions... > > A usable and useful configuration of U-Boot, including a basic > interactive command interpreter, support for download over Ethernet > -and the capability to program the flash shall fit in no more than 128 !KiB. > +and the capability to program the flash shall fit in no more than 128 KiB. > > Keep it Fast > ^^^^^^^^^^^^ > > The end user is not interested in running U-Boot. In most embedded > -systems he is not even aware that U-Boot exists. The user wants to > +systems they are not even aware that U-Boot exists. The user wants to "The end user" is singular. > run some application code, and that as soon as possible after switching > -on his device. > +on their device. > > It is therefore essential that U-Boot is as fast as possible, > especially that it loads and boots the operating system as fast as possible. > @@ -63,7 +63,7 @@ Keep it Simple > ^^^^^^^^^^^^^^ > > U-Boot is a boot loader, but it is also a tool used for board > -bring-up, for production testing, and for other activities > +bring-up, for production testing, and for other activities. > > Keep it Portable > ^^^^^^^^^^^^^^^^ > @@ -96,13 +96,13 @@ Keep it Configurable > Section "Keep it Small" already explains about the size restrictions > for U-Boot on one side. On the other side, U-Boot is a powerful tool > with many, many extremely useful features. The maintainer or user of > -each board will have to decide which features are important to him and > -what shall be included with his specific board configuration to meet > -his current requirements and restrictions. > +each board will have to decide which features are important to them and > +what shall be included with their specific board configuration to meet > +their current requirements and restrictions. > > Please make sure that it is easy to add or remove features from a > board configuration, so everybody can make the best use of U-Boot on > -his system. > +their system. > > If a feature is not included, it should not have any residual code > bloating the build. > @@ -126,7 +126,7 @@ debug is all the more important to many of us. > * All initialization steps shall print some "begin doing this" message before > they actually start, and some "done" message when they complete. For example, > RAM initialization and size detection may print a "RAM: " before they start, > - and "256 MB\n" when done. The purpose of this is that you can always see > + and "256 MB\\n" when done. The purpose of this is that you can always see %s/MB/MiB/ > which initialization step was running if there should be any problem. This > is important not only during software development, but also for the service > people dealing with broken hardware in the field. > @@ -143,8 +143,8 @@ Please always keep in mind that there are at least three different > groups of users for U-Boot, with completely different expectations > and requirements: > > -* The end user of an embedded device just wants to run some application; he > - does not even want to know that U-Boot exists and only rarely interacts with > +* The end user of an embedded device just wants to run some application; they Please, don't mix singular and plural. > + do not even want to know that U-Boot exists and only rarely interacts with > it (for example to perform a reset to factory default settings etc.) > > * System designers and engineers working on the development of the application > @@ -157,7 +157,7 @@ and requirements: > their hardware is easy for them. > > * Make it easy to test. Add debug code (but don't re-invent the wheel - use > - existing macros like debug() or debugX()). > + existing macros like debug()). %s/debug()/log_debug()/ Best regards Heinrich > > Please always keep in mind that U-Boot tries to meet all these > different requirements.
On Wed, Jul 13, 2022 at 07:40:03PM +0200, Heinrich Schuchardt wrote: > On 7/11/22 19:14, Tom Rini wrote: > > - Remove some missed wiki markup, and escape a "\n" correctly. > > - Use gender-neutral language to refer to the user, consistently. > > > > Cc: Claudius Heine <ch@denx.de> > > Cc: Heinrich Schuchardt <xypron.glpk@gmx.de> > > Signed-off-by: Tom Rini <trini@konsulko.com> > > --- > > Changes in v2: > > - None > > --- > > doc/develop/designprinciples.rst | 24 ++++++++++++------------ > > 1 file changed, 12 insertions(+), 12 deletions(-) > > > > diff --git a/doc/develop/designprinciples.rst b/doc/develop/designprinciples.rst > > index 43aeb5dacf5f..e5e12dca79f5 100644 > > --- a/doc/develop/designprinciples.rst > > +++ b/doc/develop/designprinciples.rst > > @@ -28,15 +28,15 @@ millions... > > > > A usable and useful configuration of U-Boot, including a basic > > interactive command interpreter, support for download over Ethernet > > -and the capability to program the flash shall fit in no more than 128 !KiB. > > +and the capability to program the flash shall fit in no more than 128 KiB. > > > > Keep it Fast > > ^^^^^^^^^^^^ > > > > The end user is not interested in running U-Boot. In most embedded > > -systems he is not even aware that U-Boot exists. The user wants to > > +systems they are not even aware that U-Boot exists. The user wants to > > "The end user" is singular. First person singular they is normal usage. Talk to me on IRC if you want me to dig up one of the essays on the extensive history of first person singular they :) > > run some application code, and that as soon as possible after switching > > -on his device. > > +on their device. > > > > It is therefore essential that U-Boot is as fast as possible, > > especially that it loads and boots the operating system as fast as possible. > > @@ -63,7 +63,7 @@ Keep it Simple > > ^^^^^^^^^^^^^^ > > > > U-Boot is a boot loader, but it is also a tool used for board > > -bring-up, for production testing, and for other activities > > +bring-up, for production testing, and for other activities. > > > > Keep it Portable > > ^^^^^^^^^^^^^^^^ > > @@ -96,13 +96,13 @@ Keep it Configurable > > Section "Keep it Small" already explains about the size restrictions > > for U-Boot on one side. On the other side, U-Boot is a powerful tool > > with many, many extremely useful features. The maintainer or user of > > -each board will have to decide which features are important to him and > > -what shall be included with his specific board configuration to meet > > -his current requirements and restrictions. > > +each board will have to decide which features are important to them and > > +what shall be included with their specific board configuration to meet > > +their current requirements and restrictions. > > > > Please make sure that it is easy to add or remove features from a > > board configuration, so everybody can make the best use of U-Boot on > > -his system. > > +their system. > > > > If a feature is not included, it should not have any residual code > > bloating the build. > > @@ -126,7 +126,7 @@ debug is all the more important to many of us. > > * All initialization steps shall print some "begin doing this" message before > > they actually start, and some "done" message when they complete. For example, > > RAM initialization and size detection may print a "RAM: " before they start, > > - and "256 MB\n" when done. The purpose of this is that you can always see > > + and "256 MB\\n" when done. The purpose of this is that you can always see > > %s/MB/MiB/ Plenty of memory related notices, even in the docs, use "MB". Lets just put this on the pile to adjust later.
diff --git a/doc/develop/designprinciples.rst b/doc/develop/designprinciples.rst index 43aeb5dacf5f..e5e12dca79f5 100644 --- a/doc/develop/designprinciples.rst +++ b/doc/develop/designprinciples.rst @@ -28,15 +28,15 @@ millions... A usable and useful configuration of U-Boot, including a basic interactive command interpreter, support for download over Ethernet -and the capability to program the flash shall fit in no more than 128 !KiB. +and the capability to program the flash shall fit in no more than 128 KiB. Keep it Fast ^^^^^^^^^^^^ The end user is not interested in running U-Boot. In most embedded -systems he is not even aware that U-Boot exists. The user wants to +systems they are not even aware that U-Boot exists. The user wants to run some application code, and that as soon as possible after switching -on his device. +on their device. It is therefore essential that U-Boot is as fast as possible, especially that it loads and boots the operating system as fast as possible. @@ -63,7 +63,7 @@ Keep it Simple ^^^^^^^^^^^^^^ U-Boot is a boot loader, but it is also a tool used for board -bring-up, for production testing, and for other activities +bring-up, for production testing, and for other activities. Keep it Portable ^^^^^^^^^^^^^^^^ @@ -96,13 +96,13 @@ Keep it Configurable Section "Keep it Small" already explains about the size restrictions for U-Boot on one side. On the other side, U-Boot is a powerful tool with many, many extremely useful features. The maintainer or user of -each board will have to decide which features are important to him and -what shall be included with his specific board configuration to meet -his current requirements and restrictions. +each board will have to decide which features are important to them and +what shall be included with their specific board configuration to meet +their current requirements and restrictions. Please make sure that it is easy to add or remove features from a board configuration, so everybody can make the best use of U-Boot on -his system. +their system. If a feature is not included, it should not have any residual code bloating the build. @@ -126,7 +126,7 @@ debug is all the more important to many of us. * All initialization steps shall print some "begin doing this" message before they actually start, and some "done" message when they complete. For example, RAM initialization and size detection may print a "RAM: " before they start, - and "256 MB\n" when done. The purpose of this is that you can always see + and "256 MB\\n" when done. The purpose of this is that you can always see which initialization step was running if there should be any problem. This is important not only during software development, but also for the service people dealing with broken hardware in the field. @@ -143,8 +143,8 @@ Please always keep in mind that there are at least three different groups of users for U-Boot, with completely different expectations and requirements: -* The end user of an embedded device just wants to run some application; he - does not even want to know that U-Boot exists and only rarely interacts with +* The end user of an embedded device just wants to run some application; they + do not even want to know that U-Boot exists and only rarely interacts with it (for example to perform a reset to factory default settings etc.) * System designers and engineers working on the development of the application @@ -157,7 +157,7 @@ and requirements: their hardware is easy for them. * Make it easy to test. Add debug code (but don't re-invent the wheel - use - existing macros like debug() or debugX()). + existing macros like debug()). Please always keep in mind that U-Boot tries to meet all these different requirements.
- Remove some missed wiki markup, and escape a "\n" correctly. - Use gender-neutral language to refer to the user, consistently. Cc: Claudius Heine <ch@denx.de> Cc: Heinrich Schuchardt <xypron.glpk@gmx.de> Signed-off-by: Tom Rini <trini@konsulko.com> --- Changes in v2: - None --- doc/develop/designprinciples.rst | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-)