Issue #44: Update the README file #62

Closed
wants to merge 4 commits into
from

Projects

None yet

3 participants

@Nebelhom

This pull request addresses Issue #44: Update the README file

I appended the --help output to the README and adjusted the format accordingly. It seemed the best way forward to have all documentation in one place.

@davehunt, @whimboo

I see this here as a start. If there is more, that you want in then best post it in here.

Thanks

@davehunt
Member

I would prefer to see this in the same format as it appears in the --help text. See https://github.com/mozilla/b2gperf/blob/master/README.md as an example. It's also much easier to update then, as it's more or less copy/paste.

@Nebelhom

@davehunt ok, now that the timeout pull request has been merged, I updated this pull request according to your suggestions.

Thanks for the input.

@davehunt
Member

hmm.. doesn't look particularly pretty :P you might hate me for this, but do you think you could improve is by doing a couple of things?

  • Ignore the line wrap that you get from --help and let the lines continue. This will save vertical space.
  • Where an option is just too long for help text to be beside it (but is forced onto a new line) increase the indent for all help text to allow it to flow on a single line.

For example, instead of:

  -v VERSION, --version=VERSION
                        Version of the application to be used by release and
                        candidate builds, i.e. "3.6"
  --extension=EXTENSION
                        File extension of the build (e.g. "zip"), default:
                        the standard build extension on the platform.
  --username=USERNAME   Username for basic HTTP authentication.
  --password=PASSWORD   Password for basic HTTP authentication.

Have:

  -v VERSION, --version=VERSION
                          Version of the application to be used by release and candidate builds, i.e. "3.6"
  --extension=EXTENSION   File extension of the build (e.g. "zip"), default: the standard build extension on the platform.
  --username=USERNAME     Username for basic HTTP authentication.
  --password=PASSWORD     Password for basic HTTP authentication.

I know, it kinda defeats my argument for copy/paste. On that basis please feel free to tell me it looks fine as it is! :P

@Nebelhom

@davehunt hmmm... it really depends on what you want out of this. The pros for my current commit are ease of maintenance (it is literally copy and paste) and the fact that you see everything at first glance.

Your suggestions make the README look pretty, but in turn you'd have to scroll left and right to read it all. I, personally, would find that annoying.

I'll change it the way you mentioned to see how it looks. We can always revert back to this commit if doesn't look as pretty as you hoped for ;)

@Nebelhom

@davehunt Have a look if you like it more this way. I would wrap the description text around to a new line after a certain amount of characters, so that scrolling is not necessary, but again we're getting further and further away from the simple copy and paste job.

@davehunt
Member

I do prefer this version, but I agree that we should probably wrap to avoid horizontal scrolling. I also meant for an upper limit to the first 'column' so there wouldn't be so much whitespace. See my previous comment were the -v VERSION --version=VERSION option forces the description onto the next line.

@Nebelhom

@davehunt to be honest, I thought you made a mistake there (with the version description on the next line) ;) sorry, I shall fix it and try to go for a max length at which point the line will be wrapped around

@Nebelhom

@davehunt hmmm... not sure if that is now so much better than the very first one...

Ach well, all the information is in there now, and if you like it that way, then I am happy ;)

@davehunt
Member

I could probably pick over this for a long time :P Essentially, I'm happy that all the information is there, even if it's doesn't look fantastic. I'll leave this for @whimboo to weigh in and merge if he's happy. We can always tweak it later.

@whimboo
Collaborator
whimboo commented Mar 22, 2013

Looks good to me. @davehunt please merge this pull. For the future I wonder if we could automate the update of the readme. Otherwise each pull which changes the cmd line interface of mozdownload would also have to update the readme file.

@whimboo
Collaborator
whimboo commented Mar 22, 2013

Only one thing to do for the merge... please use a better commit message. Thanks.

@Nebelhom

I called 'git commit --amend' and then forced a push. I hope this commit message is better, although I wasn't sure what was wrong with the previous one. I made sure punctuation is better and the message is more concise, but if you could tell me, what was wrong with the message, then I shall make sure, it won't happen in the future.

Thanks.

@davehunt
Member

@Nebelhom I don't think @whimboo was referring to your latest commit message. I will squash before merging and will use a commit message that's appropriate to the changes.

@davehunt
Member

Landed in 5e68c96

@davehunt davehunt closed this Mar 26, 2013
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment