New Documentation for barebox
s.hauer at pengutronix.de
Thu Jun 26 11:17:53 PDT 2014
On Thu, Jun 26, 2014 at 11:36:15AM +0200, Holger Schurig wrote:
> 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
> 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.
I usually write barebox with a small 'b' even at the beginning of a
sentence, but you're right with the other headlines, they should start
with a capital letter.
> After getting barebox there should be a brief mention of the branches,
> e.g. difference between next & master.
Very good. I thought that aswell, but forgot to write it.
> Configuration: at "make menuconfig" also "make xconfig" should be mentioned.
make nconfig aswell?
> "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!
This is already in Documentation/boards/imx.rst where I think is a
> "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.
I never thought about tftp being an automount by itself, but you are
right. NFS is different though, it really does network transfers during
> "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.
Have you looked what is rendered with a colon? (I haven't)
> "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 at 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.
Agreed. That was just the prompt I copy/pasted, but right, it should be
> "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
That would be something for a developer manual, but ok, a git link
should do it for now.
> "13. Prebootloader": the sentence "Use the barebox-flash-image link
> which always points to the correct image" doesn't sound like proper
I am open for better suggestions. I tend to stand in my own way when I
think about a sentence for too long ;)
> 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 :-)
You're probably right ;)
Pengutronix e.K. | |
Industrial Linux Solutions | http://www.pengutronix.de/ |
Peiner Str. 6-8, 31137 Hildesheim, Germany | Phone: +49-5121-206917-0 |
Amtsgericht Hildesheim, HRA 2686 | Fax: +49-5121-206917-5555 |
More information about the barebox