Re: New Documentation for barebox

[Holger Schurig <holgerschurig@gmail.com>]

Some random annotations. Please comment, after feedback I'll provide a
bunch of patches for this. I don't do the patches right away, because
you may still work currently in that area, so it would only produce
conflicts.


User manuel "2. System setup" should be in an appendix. Nothing here
is really related to barebox itself. It contains just helpful hints.

I would capitalize some headlines, e.g. in the user manual "3.
Barebox", "4. Networking", "6. Memory areas" etc   The same for the
two headlines starting in lower-case in the main index.html. Maybe "3.
barebox" can stay lowercase, because barebox is an "Eigenname", dunno.
It looks however a bit ugly when it's lowercase.

After getting barebox there should be a brief mention of the branches,
e.g. difference between next & master.

Configuration: at "make menuconfig" also "make xconfig" should be mentioned.

"3.3. Compilation", shouldn't it be "make ARCH=xxx" ?  Ha, maybe it's
just an old habit of me ...

"3.4 Starting Barebox" could get a link to the i.MX USB downloader.
Very fine tool!

"4.2. Network filesystems": hinting on automount for tftp-file system
is a bit moot. Because at the "mount -t tftp AAA BBB" nothing happens,
tftp is, so to say, an automount by itself. I haven't yet used NFS
from barebox, but I guess it is the same there. So I'd remove the
automount reference from this place completely.

"5. Automount", the same, better use sdcard as an example,. not tftp.

"7.2. Device parameters": Better write "HINT: barebox has ..." (e.g.
with a colon). The same applies to the "NOTE" annotations.

"8.1 Hush features" should "let X=$A/2" be there?  Many people (ok, it
was just me) look there if they need to calculate in the shell after
finding out that X=$(($A/2)) doesn't work ...

"10. Configuration variable": this should be neared the device
parameters. I'd add a hint that with "devinfo global" one can see all
defined global variables.

several places: the "barebox@Genesi Efika MX Smartbook:/" should be
reduced to "barebox:/", as it is usually irrelevant if that example
was done on an Efika board or not.

"11. Updating barebox", it says that a board can register an update
handler, but doesn't have an example or a link to where / how this
could be done. Or even a link directly to the git tree with a working
example.

"13. Prebootloader": the sentence "Use the barebox-flash-image link
which always points to the correct image" doesn't sound like proper
english.


Abbreviation should be capizalized as well, therefore headline "ram
filesystem" -> "RAM filesystem"

I think that in english one should write "file systems", not
"filesystems". But i may be wrong. But I'm quite sure that the word
"filesystemtype" (in the RAM file system chapter) is too long for any
englishman :-)

_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox