-
Notifications
You must be signed in to change notification settings - Fork 288
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Update flac.md: Reordering and updating options descriptions & more #769
Conversation
…me of the examples I am not sure about the organization of the initial part of the document, to be honest. For example the way it promises examples before options, but before the examples sections it gives examples (on using stdin). Anyway, here are the most significant changes I made: - Some in the examples - Options are reorganized to match the flac -h order - I used _underscores_ for italics, avoiding some formatting issue that arose from triple asterisks - Some " " inserted - you will all too easily need them when using -T - but I dared not use too many of them. ... and some more text tweaks.
Thanks! I'll take a look. |
Thanks! Looks good. Please consider my comments. One more thing:
So, previously, it didn't render correctly in github but did render correctly in pandoc (html and man page). With this change, it renders correctly in github but not in pandoc. I think pandoc is more important, so please revert this change. |
A few brief questions, reverse order, before I give it a go:
|
Sorry, I don't understand your question.
I think it is too terse, yes. I'd prefer (This option is on by default). I'd say, in a man page there is room enough to not be overly concise.
Then shortened it is! |
EDIT:
What I was thinking of would output e.g. Looking further into how to resolve it: the document is not consistent. Some instances it uses capital letters to describe what user must fill in, others do not: So even when sorting out a policy for CAPITALS or not, we might think of one out of two-and-a-half:
|
Following xiph#769 , and also: - Re-wrote the section on apodization functions - Search-replaced dot space space by dot space
I did a new attempt locally at H2Swine@7125fa9 , but before I figure out how to update a PR with a new file (or should one open a new?), you can rather look at it to strike down whatever proposed changes are not that good. That in particular goes for the attempts at fixing the previous reply in this thread. There are a couple of more changes proposed.
Then not yet done:
|
Lets get back to the beginning: this was and is, first and foremost, a manpage. It is a *nix concept that you might be familiar with. I'd like to stick with the convention there. The convention seems to be that everything a user has to change (i.e., that is not to be taken literal) is underlined and ALLCAPS. Now, markdown doesn't support underlining in any way, and manpages use a monospace font which doesn't support italics, so the underlined parts were converted to italics in the markdown/html. Proposal: Don't apply any markup to symbols. So,
Just add another commit to the branch that belongs to this pull request.
Yeah, I don't know where these came from, I think replacing with single spaces is fine.
Thanks
In the order you want them to end up in the FLAC file. First channel first, second channel second etc. I don't think not adding this is a big deal, this is specific enough that people can just try and see what happens a few times if they don't know where to find the format specification. Raw input is messy anyway.
No, between negative infinity and 1. I don't think it is necessary to document however, as I am not sure it is very useful. However, a negative overlap gives very small windows with gaps between them. So, when you specify
I don't know, experimenting beyond the presets is really that, experimenting. I'm not sure there should be guidelines on that in the manpage. When someone gets to this point in the manual, everything already works anyway, it is not some feature that can be enabled or disabled or something, it is just that maybe, perhaps, a tiny bit smaller file can be generated. |
I'll have a look at the following shortly (object if I have misunderstood):
I am going to presume it shall be in all caps,
This is the comprehensive help, so I am putting in a reference to the format specification there. I assume it is with the order as in the format spec section 9.1.3 table 16 - for example, the first one in the stream will go to "what the FLAC format by default (absent channel mask tag) thinks is" FL, the second to FR, and the third to FC except if channel count is 4?
I take that to mean that it is fine to remove the wording about partial/punchout 2 to 6, as it could look like such a recommendation. I agree we should be careful not to present "more functions as any bang for the buck", but it may still be a point that subdivide_tukey is developed to recycle calculations for more windows cheaper. I'll chew on a formulation that you can reject. |
Edit: And this sentence ... is there supposed to be anything more comprehensive at all? Delete it? |
Following discussion up to xiph#769 up to replies 12-13.
I had another shot at it (did I commit it right between this comment and the previous?! Edit: Right now I discovered the "Convert to draft" option, which maybe would be the right thing for all that I know - I hope I didn't mess up anything by merely requesting review). There are a few things I have not touched, not knowing completely what should be done to them all:
Edit2, forgot:
|
Yes
I think so yes. As far as I know
Yes
Okay. This is behaviour of getopt, I don't know all the nooks and crannies of it. I suppose the equals sign isn't necessary then. Still, probably better not to mention it, or it gets even more confusing.
You can remove that. Can you imagine,
This seems to have happened exactly as it should be. Not using the 'draft PR' option is also the proper way, because on draft PRs, reviewing is impeded/blocked. I only use the draft PR option to signal that nobody should care to look at it yet, which isn't the case here.
You could move it up, but people don't read such a document top-to-bottom. At least, I don't. I agree that it applies to the whole man page, but similar specs elsewhere aren't as complicated. Also, the pipe symbol is literal in the picture specification, whereas it means or elsewhere in the document.
I think it is wise to merge this as soon as there are no loose ends, and not wait for further improvements. It is better to have several smaller commits than one big commit, as long as the commit is 'self-contained'.
MM:SS is a rather standard way of writing I'd say. I'm not sure that needs any clarification. |
New one in a minute, hoping I'm about to converge on what I've actually touched upon. Will describe changes relative to previous one here.
I agree. Although I did a little bit on lines 44 to (new) 56, but any changes between that and the EXAMPLES section can be ... for later. EXAMPLES:
OPTIONS: First this removal I did:
As an aside, I actually suggest to consider: -H should not give an error, rather a short sentence that says "For long help, use man page / HTML doc / [URL]."
|
I'd like to merge this now, if you are OK with that. |
One n replaced by *N*
Oh, sorry for one little detail I overlooked: at a glance and scroll, I found one single "n" shining at my eyes, that now is CapItalic-ized. Apart from that, I know that the .md file's linebreaks are not at consistent character width, but from your changes today I am assuming you have full control over what is needed, so ... merge if/when you want to. Afterwards I'll scratch my head a little for possible changes to the "GENERAL USAGE". (That is not to say I will actually come up with any improvement.) |
I am not sure about the organization of the initial part of the document, to be honest. For example the way it promises examples before options, but before the examples sections it gives examples (on using stdin and redirects).
Anyway, here are the most significant changes made:
... and some more text tweaks.