mail archive of the barebox mailing list
 help / color / mirror / Atom feed
From: Sascha Hauer <s.hauer@pengutronix.de>
To: Holger Schurig <holgerschurig@gmail.com>
Cc: "barebox@lists.infradead.org" <barebox@lists.infradead.org>
Subject: Re: New Documentation for barebox
Date: Thu, 26 Jun 2014 20:17:53 +0200	[thread overview]
Message-ID: <20140626181753.GC14257@pengutronix.de> (raw)
In-Reply-To: <CAOpc7mEXX4GQh2oxGO1y7Y8bNsgf=DZzOwc9aBZwToftk=vv8w@mail.gmail.com>

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
> conflicts.
> 
> 
> User manuel "2. System setup" should be in an appendix. Nothing here
> is really related to barebox itself. It contains just helpful hints.

Ok.

> 
> 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
better place.

> 
> "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
mounting.

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

Ok.

> 
> "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 ...

Sounds good.

> 
> "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.

Agreed. That was just the prompt I copy/pasted, but right, it should be
reduced.

> 
> "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.

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
> english.

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"

Yes.

> 
> 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 ;)

Sascha

-- 
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 |

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

  reply	other threads:[~2014-06-26 18:18 UTC|newest]

Thread overview: 19+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2014-06-26  8:51 Sascha Hauer
2014-06-26  8:51 ` [PATCH 1/7] ubiformat: avoid macros in help text Sascha Hauer
2014-06-26  8:51 ` [PATCH 2/7] automount: fix description typo Sascha Hauer
2014-06-26  8:51 ` [PATCH 3/7] commands: addpart: Improve description Sascha Hauer
2014-06-26  8:51 ` [PATCH 4/7] Documentation: remove doxygen documentation Sascha Hauer
2014-06-26  8:51 ` [PATCH 5/7] Documentation: remove remaining documentation Sascha Hauer
2014-06-26  8:51 ` [PATCH 6/7] Documentation: remove devicetree docs Sascha Hauer
2014-06-26  8:51 ` [PATCH 7/7] Documentation: Add new sphinxs docs Sascha Hauer
2014-06-26  9:02 ` New Documentation for barebox Holger Schurig
2014-06-26  9:09   ` Sascha Hauer
2014-06-26  9:36 ` Holger Schurig
2014-06-26 18:17   ` Sascha Hauer [this message]
2014-06-26  9:54 ` Holger Schurig
2014-06-26 10:01   ` Lucas Stach
2014-06-26 10:11     ` Holger Schurig
2014-06-26 10:28 ` Antony Pavlov
2014-06-26 15:36   ` Sascha Hauer
2014-06-26 10:31 ` Robert P. J. Day
2014-06-26 18:56   ` Sascha Hauer

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20140626181753.GC14257@pengutronix.de \
    --to=s.hauer@pengutronix.de \
    --cc=barebox@lists.infradead.org \
    --cc=holgerschurig@gmail.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox