Offline Help Manual Available!! Version .85 (final beta)

Started by Harbinger, September 11, 2009, 17:53:03

Previous topic - Next topic

Harbinger

OHM .1 BETA SITE DOWN -- don't use!!
OHM .2 BETA SITE DOWN -- don't use!!
OHM .4 BETA SITE DOWN -- don't use!!
OHM .6 BETA SITE DOWN -- don't use!!
OHM .85 BETA final - outdated, don't use this!

Get the OHM 1.0 release instead!

The beta version is now available! Download the latest PDF draft of the ModPlug Tracker Offline Help Manual (OHM) from the links above.
.85 includes the much-anticipated Reference section.

I'm requesting the help of both new and veteran users alike, but for different reasons.

MPT rookies: What questions arise (and are not answered) as you read each section? (The Reference section comes later, so put those questions aside.) Does the layout and walk-thru help or hinder your learning of MPT? Is there any text which you just can't figure out, even after trying it out in ModPlug itself?

MPT veterans: The reason this is beta is because i need the data vetted for errors or confusing syntax. If you KNOW a statement in this draft is incorrect (or badly worded enough to be misleading), i need to know. If you BELIEVE it's incorrect, tell me that a statement should be verified, so i can test it (if i can).

Syntax for this thread

When bringing certain statements to my attention, create an independent post. That is, don't worry if it's already been brought up by someone else. If you noticed it when you read the PDF, then raise the issue in your own post.

You don't need to quote the text (although you may). What will really help is the version of the manual (found in the file name), and the chapter and subsection you find the error/problem. Then follow it directly with one of the following headings:
"KNOWN:" and your correction to the statement that i wrote up, or
"VERIFY:" and what you thought was true that runs counter to the Manual statement, or
"CONFUSING:" and the question which arises when you read the text, or
"REQUEST:" and what changes you'd like to see to make the section/paragraph better.

So as an example, your post should look something like this:

QuoteOHM .2

CH 4 "New Note Actions"
VERIFY: I learned somewhere that Duplicate Check does not work correctly.

CH 14 "Creating Tunings"
CONFUSING: I couldn't understand if the new tunings should be moved to the Local category or to the Tune-specific category.

plus whatever other issues were raised in your mind as you read thru the manual.
I want to hear from all ModPlug users (and former users psishock!:wink:). The only way we'll have a truly complete manual is for anyone who reads it to tell me where it fails its purpose. 8)

Get out your reading glasses, boys!!

Saga Musix

Nice effort. I just had a quick glance, so here are some small mistakes I've found:

CH 1 "histroy"
KNOWN: modplugcentral.com does not exist.

CH 6 "Player tab"
KNOWN: I'd appreciate it if you would mention that enabling all those options in the upper frame is not recommended, as it will not be saved in the modules and it will also be applied to *all* songs.

CH 8 "Filters"
KNOWN: ModPlug doesn't have a bandpass filter. "Channel default" simply means that the last setting (highpass or lowpass filter) of this channel will be used. The default filter type is lowpass.

CH 20 Appendix A - MOD Effects
CONFUSING: it would be better to write that 500 is the same as 300, and 600 is the same as 400.

CH 20 Appendix A - XM / S3M Effects
KNOWN: Rxy / Qxy (Retrigger) in XM / S3M works just like in IT, so your description is incomplete.


Since I love nutpicking and hate wrong apostrophes, I want to tell you that there is nothing like a plural apostrophe. "VSTi's" is simply wrong. You also don't write "midi keyboard's", do you? It's a bit of a riddle to me why people use it only in *some* cases, maybe it has something to do with abbreverations or short words, I don't know.


BTW: I find it funny that you actually got the 8xx command in MOD files (set panning) correct, although the current version of OpenMPT still gets it wrong... :) (OpenMPT currently only uses the values from 800 to 880, even though it should use 800 to 8FF). Don't fix this, though, as you would have to fix it again soon then. :)
» No support, bug reports, feature requests via private messages - they will not be answered. Use the forums and the issue tracker so that everyone can benefit from your post.

uncloned


LPChip

Quote from: "Jojo"Since I love nutpicking and hate wrong apostrophes, I want to tell you that there is nothing like a plural apostrophe. "VSTi's" is simply wrong. You also don't write "midi keyboard's", do you? It's a bit of a riddle to me why people use it only in *some* cases, maybe it has something to do with abbreverations or short words, I don't know.

I learned at school that you use apostrophes when the last letter is a vowel. VSTi ends with an i, and by that rule, it would have VSTi's.
"Heh, maybe I should've joined the compo only because it would've meant I wouldn't have had to worry about a damn EQ or compressor for a change. " - Atlantis
"yes.. I think in this case it was wishful thinking: MPT is makng my life hard so it must be wrong" - Rewbs

Saga Musix

Which is wrong (you can tell that your teacher :nuts:)
http://en.wikipedia.org/wiki/Apostrophe#Use_in_forming_certain_plurals
The only rule that *could* apply here is the first, however I don't see that the "i" in VSTi is a single letter.

Anyway, this is kinda OT.
» No support, bug reports, feature requests via private messages - they will not be answered. Use the forums and the issue tracker so that everyone can benefit from your post.

psishock

I'm as calm as a synth without a player.  (Sam_Zen)

Sam_Zen

0.618033988

bvanoudtshoorn

A few little things from a quick scan through: (mostly find-and-replace stuff)

Maybe increase the line-height (line-spacing in Word?) to 1.5 to improve legibility -- when reading from a screen, dense text is hard to parse, generally speaking. :)

You should maybe have "field" as a labelled part of your terms, rather than as an afterthought on "column".

"Hexidecimal" should be "Hexadecimal"

Maybe state that you're using the $-convention for Hex. There are other conventions (like 0x), so this might confuse people.

"Thru" isn't a word. "Through" is. :)

In a few places, there's a lower-case "i" for the word "I".

As mentioned, "VSTi" has the plural form "VSTis" or, if you prefer, "VSTIs".

Perhaps use the same font as the body text in your tables, rather than two completely different fonts. :) (My typesetter side is showing...)

Numbers below or equal to ten should be written out in full. (Some style guides suggest numbers below 100, but it's up to you.)

Maybe include page numbers in the footer, and chapter numbers and names in the header of your pages. (Except, of course, where you're starting a chapter -- then it should only be the page number.)

Chapters should always start on a new page. (There's an option in the stylist to insert page breaks before the heading.)

You need to enable widow and orphan control, and set headings to always stay with the following paragraph.

All in all, though, it looks good! :) I might do a full proof-read when the revision number ticks over to 0.2. It'd actually be good for the 12-hour plane trip I'm taking in two weeks. :)

Sam_Zen

0.618033988

Saga Musix

QuoteNumbers below or equal to ten should be written out in full. (Some style guides suggest numbers below 100, but it's up to you.)
I'm not sure if this is completely true in English, but in German it's up to 12, not 10 - as "eleven and twelve" are still very short words, the "long ones" start with thirteen.
» No support, bug reports, feature requests via private messages - they will not be answered. Use the forums and the issue tracker so that everyone can benefit from your post.

Relabsoluness

Some comments based on a quick look:

Multiple CHs:
CONFUSING: Manual uses "Modplug tracker" while the application refers itself as OpenMPT.

CH1:
CONFUSING:
Quote8. Good MIDI implementation through channel effects, including
input and playback with external MIDI devices.
9. Full use of VST technology
I wonder how many understand what these are supposed to mean.


CH6:
KNOWN:
QuoteCombine MIDI volume to Note Velocity: When inputting a note
from the MIDI keyboard, the key velocity will be entered as a volume
effect (vxx) instead of the velocity (:xx).
Wrong. Whether enabled or not, vxx is the command used. What this option means is that if enabled, MIDI keyboards volume settings has an effect on the effective volume that MPT uses. So for example if you're entering notes from MIDI keyboard and volume v64 gets written each time and the option is disabled, the volume doesn't change even if you modify the volume setting in your MIDI keyboard. If the option is enabled, the volume can be lower than 64 if the volume setting in MIDI keyboard is lowered.

CH6:
KNOWN:
QuotePass MIDI to Active Instrument: When macros use MIDI CC
messages, playback will send these messages to the keyboard controller. Note that this is still in the testing phase.
Wrong. If enabled, MIDI data that MPT receives from external device will be passed to active instrument plugin.

CH14:
KNOWN:
QuoteIt was thought that MPT actually has this feature using the "Finetune" box in the Tunings dialog, but, as of this edition, the author was unable to verify its function.
Finetune defines how portamento effects behave - the more finetune steps, the "more portamento" is needed to change the note.


On the whole, looks a real effort has been taken to write the manual - perhaps MPT is finally getting a decent manual.

Rakib

Great job Harbinger!

One suggestion I have is have a more visual profile, now its plain text and some images. Is is possible to make it more visual attractive?
^^

Harbinger

Thanks for your encouragement and critiques.

Some quick notes:

1. English was a cinch for me in school. I'm very aware of my grammar and spelling quirks (except of course for obvious typos), in relation to what's proper.
-- When i write, i never capitalize the pronoun I, except in VERY formal writing. (I know a couple of other people who do this but we all have different reasons.) That won't change. However, i want to depersonalize this manual as much as possible, so that should be corrected.
-- I learned a long time ago, in junior high actually, that uncapitalized, "acronymed" nouns (such as abc's and rpm's) -- especially those that end in a vowel -- are pluralized with an apostrophe - s. I will continue to use "VSTi's".
-- This is not a formal document. When i release the .doc format, you may freely edit it so sentences don't end in a preposition, punctuation marks fall within quotes that end a clause or sentence, numbers are written out, informal words like "altho" and "thru" are spelled correctly, etc. Then you can release it as the "Grammar Nazi" version or the "Professional Typesetting" version! :lol:
2. The goal here is to ease new users of MPT into using this application. The Reference section will be detailed and heavily directed by HOW ModPlug gets things done. Since there is little criticism on this aspect of the beta version of this part of the manual, i will view this goal as a success. 8)
3. Visual appeal is highly subjective and VERY dependent on the reader. Many readers LOVE lots of pictures especially in a technical document so it walks them through without having to be there. Others like as few graphic distractions as possible, as long as the text is clear and descriptive. I will try to include more images, but remember i will never get it perfect for everyone.
4. The Effect Commands have been poorly assembled, so i admit to rushing that. There are some subtle differences in how MPT applies Channel FX in the various track formats. The next version hopefully will see that section thoroughly repaired.

I was already working on the .2 beta version, but i will copy this page and take it home with me to incorporate your ideas. Thanks especially to Jojo and Relabsoluness, as my biggest concern is the FACTUAL data of what i'm writing. Keep those corrections coming! 8)

Saga Musix

On a side note, didn't M$ Word automatically capitalize "I"? I haven't used it for ages (I use OpenOffice myself), but I'm very sure it did.
» No support, bug reports, feature requests via private messages - they will not be answered. Use the forums and the issue tracker so that everyone can benefit from your post.

bvanoudtshoorn

Quote from: "Harbinger"...Then you can release it as the "Grammar Nazi" version or the "Professional Typesetting" version!

Well, as I said, I had planned to do a full proof in the near future. :) I'm not a Grammar Nazi, but I did work as a proof-reader and typesetter for a while. As it's your document, you are, of course, entitled to do what you want with it in terms of grammar etc., but personally, I think that it's good enough to be considered for inclusion as an official OpenMPT doc. As such, I think that it's worthwhile ensuring that it adheres to English which is best-understood internationally -- that means no Americans, no Britishisms, and no Australianisms. :)

Great work overall, though, Harbinger -- when I do my full proof, I'll hopefully (or perhaps not 'hopefully') catch some factual errors. :D

@Jojo: Yes, Word should do this automatically; so does OpenOffice.org. In both, though, you can turn it off fairly easily, which I'm guessing is what Harbinger's done.