w8jcik opened a new pull request #337: URL: https://github.com/apache/incubator-nuttx-apps/pull/337
## Summary - All `README` and `README.txt` were renamed (`git mv`) into `README.md`. - Changed format of headers to `#`, `##` and `###`. - Code sections fenced with `` ``` `` - Fragments of code in sentences marked with `` ` `` - Changed format of lists. - Simplified indentation. - Replaced `NOTE:` with `**Note**:`, same with `NOTES:`, `WARNING:` and similar. - Fixed some typos and inconsistencies. - Changed titles from `README` (most of them was like this) to something more meaningful. - Added some tables. - Removed some typos and inconsistencies. - Rewrapped at column `80`. ## Impact - Markdown improves readability. Compare this https://github.com/apache/incubator-nuttx-apps/blob/master/nshlib/README.txt and this https://github.com/w8jcik/incubator-nuttx-apps/blob/master/nshlib/README.md - Use standard text format for READMEs. Most of the developers are more familiar with Markdown than the previous format, so it is easier to adapt. Markdown is simpler. - It is parsable. Previous format wasn't. - Part of a bigger effort on improving accessibility of NuttX documentation. ## Testing - You can clone this fork and look at the readmes in your editor. For example: - `git clone https://github.com/w8jcik/incubator-nuttx-apps.git` - open folder in VSCode - in terminal and run `find . -name README.md` - Ctrl+Click on list of files in the terimnal to open them - Install `bierner.markdown-preview-github-styles` extension to see a preview on the side. - Without extension some syntax highlighting should be already present in files. - You can look through the files in GitHub - [netutils/README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/netutils/README.md) - [netutils/discover/README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/netutils/discover/README.md) - [netutils/ftpc/README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/netutils/ftpc/README.md) - [netutils/telnetd/README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/netutils/telnetd/README.md) - [README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/README.md) - [wireless/bluetooth/btsak/README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/wireless/bluetooth/btsak/README.md) - [wireless/ieee802154/i8sak/README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/wireless/ieee802154/i8sak/README.md) - [wireless/wapi/README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/wireless/wapi/README.md) - [examples/README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/examples/README.md) - [examples/tcpblaster/README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/examples/tcpblaster/README.md) - [examples/flash_test/README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/examples/flash_test/README.md) - [examples/camera/README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/examples/camera/README.md) - [examples/json/README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/examples/json/README.md) - [examples/bastest/README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/examples/bastest/README.md) - [examples/flowc/README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/examples/flowc/README.md) - [examples/pdcurses/README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/examples/pdcurses/README.md) - [examples/telnetd/README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/examples/telnetd/README.md) - [modbus/README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/modbus/README.md) - [fsutils/inifile/README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/fsutils/inifile/README.md) - [gpsutils/minmea/README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/gpsutils/minmea/README.md) - [gpsutils/README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/gpsutils/README.md) - [testing/fstest/README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/testing/fstest/README.md) - [testing/smart/README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/testing/smart/README.md) - [testing/README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/testing/README.md) - [testing/nxffs/README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/testing/nxffs/README.md) - [testing/smart_test/README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/testing/smart_test/README.md) - [testing/cxxtest/README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/testing/cxxtest/README.md) - [system/termcurses/README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/system/termcurses/README.md) - [system/nsh/README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/system/nsh/README.md) - [system/cfgdata/README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/system/cfgdata/README.md) - [system/cdcacm/README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/system/cdcacm/README.md) - [system/i2c/README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/system/i2c/README.md) - [system/usbmsc/README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/system/usbmsc/README.md) - [system/psmq/README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/system/psmq/README.md) - [system/zmodem/README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/system/zmodem/README.md) - [system/spi/README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/system/spi/README.md) - [system/nxplayer/README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/system/nxplayer/README.md) - [system/flash_eraseall/README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/system/flash_eraseall/README.md) - [system/composite/README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/system/composite/README.md) - [tools/README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/tools/README.md) - [industry/abnt_codi/README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/industry/abnt_codi/README.md) - [interpreters/README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/interpreters/README.md) - [interpreters/bas/README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/interpreters/bas/README.md) - [interpreters/ficl/README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/interpreters/ficl/README.md) - [graphics/nxwidgets/README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/graphics/nxwidgets/README.md) - [graphics/nxwidgets/Doxygen/README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/graphics/nxwidgets/Doxygen/README.md) - [graphics/nxwidgets/UnitTests/README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/graphics/nxwidgets/UnitTests/README.md) - [graphics/tiff/README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/graphics/tiff/README.md) - [graphics/twm4nx/README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/graphics/twm4nx/README.md) - [graphics/nxwm/README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/graphics/nxwm/README.md) - [graphics/nxwm/Doxygen/README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/graphics/nxwm/Doxygen/README.md) - [graphics/pdcurs34/README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/graphics/pdcurs34/README.md) - [graphics/pdcurs34/pdcurses/README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/graphics/pdcurs34/pdcurses/README.md) - [graphics/lvgl/README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/graphics/lvgl/README.md) - [nshlib/README.md](https://github.com/w8jcik/incubator-nuttx-apps/blob/master/nshlib/README.md) ## Questions - Is wrap at column 80 fine? - What should be format of headers. Is it _Other Network Applications_ or _Other network applications_. Previously it was not completely consistent. I found the second form more readable and I would use it, but maybe I am not good with English. - Can we split group readmes, like this one https://github.com/w8jcik/incubator-nuttx-apps/blob/master/examples/README.md, into `README.md` into each `example`? - Do you see some other style violations? ## Notes - Yes I will squash it when done. - The review seems to be a bit broken. Despite me using `git mv` to rename the files ``` find . -name README -exec git mv "{}" "{}.md" \; find . -name README.txt -execdir sh -c 'git mv $(printf "%s\n" "${0%.*}").txt $(printf "%s\n" "${0%.*}").md' {} ';' ``` and commiting afterwards, GitHub shows that some files were deleted and created. We could do separate MR just for renaming. Or maybe it is just GitHub that shows it wrongly. It need to be done correctly to preserve history. - The review includes 100 change files. Maybe we could split the change into few smaller MR's. For example we could start with `examples` folder and review it first. - I will do one more check if everything is consintent before merging, but for now I would like to see if you are fine with this change and is it going in the right direction. Also we still didn't have a vote on it. ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: [email protected]
