MPT Offline Help Manual 1.00 official release NOW AVAILABLE!

[Saga Musix]

This came from you. I quote:

Installer/release package
[Imp] <Jojo> User is asked if they want to keep personal settings.

And there was nothing in the 18.03 notes to say it had been revised.

Right, the changelog for 1.18.02.00 was wasn't put together very well. This concerns the uninstaller, not the installer.

You have a terrible habit of assuming users know what you know

No need to tell me, I know that! And yes, I love nitpicking.

Perhaps when you made this feature available, you could have mentioned the fact that MODs are not saved with this flag.

Well, it's the kind of expert feature that users who need it know how to use; the rest (probably 99%) can safely ignore it. PT1.x modules are relatively rare and play well enough with this flag disabled most of the time.

"fading notes"

not much better than "continued" IMO since a background note is not necessarily fading at all. Maybe "old notes" would be the most understandable and illustrative one?

Well it's not a pitch envelope if it can used for filtering, now is it? It's best to keep referring to it as an ancillary, as-needed envelope, so i will continue to refer to it as the 3rd envelope, but taking your point into consideration, i will properly quantify it in other paragraphs discussing the envelope usage.

How about "Pitch/Filter Envelope" then? That's even what the tooltip for this envelope says, and it's probably the best name for it.


If a person does not know the difference between unsigned and signed samples, I think is actually no textual description that can really make them grasp the meaning. Hopefully those two pictures help to remove all uncertaincies:
Sample as a signed waveform

Sample as an unsigned waveform

[Harbinger]

Good pix. I think what's not clear is that the MPT's horizon line no longer represents 0 in an unsigned waveform..

I believe i have stumbled across another problem with uploading the source docs for the OHM at sourceforge. All the images used by the subdocuments are linked -- not embedded. This makes it easy to update images or upgrade them to better quality without affecting the text body.
The problem is, these links in the OOo files seem to be absolute-addressed, not relative-addressed. What this means is that when i upload the files, the images are going to be looking for MY C drive! I have tried changing their links to relative addresses ("/OHM images/image.jpg"), but when i check back they've reverted to absolute addresses again.
I have also brought an example to the library and tried the load the page with images; it's definitely NOT keeping the relative addresses. We got a problem...

I don't want to go back thru and reset the links AFTER they've been uploaded; that will take a LONG time. But i need to keep them linked, especially if users wish to create an HTML or .HLP file from them.

Any ideas? (For now i will mosey on over to OpenOffice.org to see if they have any workarounds..)

[Saga Musix]

Good pix. I think what's not clear is that the MPT's horizon line no longer represents 0 in an unsigned waveform..

Well, it does, because technically OpenMPT only "knows" signed waveforms.

About the document issues, I'm still all in for copying all the text over to a (new) wiki. There are several ways to generate PDF documents from single wiki pages as well as whole categories, so an "offline manual" could be generated automatically. And we wouldn't have all those issues with the pictures...
Another thing which I have thinking about is that we could just add a quickstart guide to the openmpt package which only consists of the most important chapters of the manual (f.e. the stuff about how sampling works and such could be left out). That way, the openmpt distribution would not be bloated too much, and the interested users could still download the full document if they want the other chapters.

[Harbinger]

I agree about the Quick Start guide. After compiling all that i knew and all that could be done with MPT, this is quite a heavy read! I have also considered putting together a Quick Start guide, which i think would be helpful, but i'm kinda burned out of technical writing right now...

I consider a Wiki version an offshoot of the source docs. I want to be able to make the source docs as easy to modify, build, or update as possible, at least as well as the source code for MPT. All versions should stem from the source text. Myself, i'm not too keen on Wiki's format nor its "look". And i'd like a slightly bit more control (that is, veto power) by devs.

And i want to sort this out before i hand over the source docs. I don't want to log in one day, even if i'd been gone for 6 mos., and find the spirit of the source docs bastardized -- at least in the original files. The docs should be editable by anyone, with edits vetoed by the current devs if the edits are not helpful or educational. Of course, anyone should be able to take the original docs, and do whatever they want to them for their own build. (The only they can't do is take credit for the source manual.)


After checking over at openoffice.org, they say that relative links are saved just not shown, but when i open the doc in this computer (which is not my home computer) even with all the images sources in the same folder level, none of the images show up.

[Saga Musix]

I consider a Wiki version an offshoot of the source docs. I want to be able to make the source docs as easy to modify, build, or update as possible, at least as well as the source code for MPT. All versions should stem from the source text. Myself, i'm not too keen on Wiki's format nor its "look". And i'd like a slightly bit more control (that is, veto power) by devs.

Sorry, but I have to disagree on all points here.

• You want the manual source to be easily editable and to be open to everyone. That's partically the principle of a wiki. Everyone can contribute, so the wiki is even "more open" than the sourcecode, where patches first have to be approved by one of the main devs.
  
• Using aforementioned extensions to MediaWiki, it's probably a matter of seconds to update/build the offline manual.
  
• You want control by project admins. That's given since pages can be locked to be editable only by certain user groups, and changes can be  reverted easily by us if we feel that something's wrong. There are extensions which provide sighting for articles (this is used on the German Wikipedia for example), but I am not to keen on that. I don't really expect any vandalism, apart from spam bots maybe (but that only happened once and then never again to the German OpenMPT wiki, and it's running for about two years already). It's not like we have to expect a huge user base editing the wiki, so keeping an eye on the edits should be fairly simple.
  

Working with wikis is great, because you never have to edit the whole document, and everyone can work on their own part at the same time. There's no problems with two people working on different articles at the same time, unlike when editing one single document file as you probably do it now. About the "look", well it can be customized but that's not really my goal. The German Wiki is an almost unmodified MediaWiki (with some changes done to the background and logo and a custom extension to display+highlight patterns). If you don't like the look, you can still use the offline manual, which is not bound to the wiki's look - It's merely generated from the wiki articles.

[g]

Would Google docs be an option?

[Saga Musix]

We were about to join all the scattered modplug resources into one page again, and then we should move out to Google Docs? No thanks. (Needless to say I'm also not a very big fan of WYSIWYG software).

[g]

We were about to join all the scattered modplug resources into one page again, and then we should move out to Google Docs? No thanks. (Needless to say I'm also not a very big fan of WYSIWYG software).

Well it was just a thought, I thought it'd be a good compromise between what you and Harbinger desire.

[Harbinger]

Well, i must defer to you, Jojo, concerning these matters -- you know far more about capabilities and limitations of various "means" out there. As long as you understand what i'm looking for, then i'll let you figure out the best way to make these wishes happen (and yours too)...

I'll get back to you on the upload to sourceforge....

[Harbinger]

You can now download the OHM source here at Sourceforge. (This may change in the future, however; keep your eyes open here.) The DL size is almost 40MB and unpacks to a size of about 66MB.

The archive is in RAR format, and requires WinRAR 2.9 or above (or a program that can de-archive RAR 2.9 files). That application is shareware but completely usable. (edit by LPChip: 7-zip can also open .rar files and is completely free. There are more archivers that support the winrar fileformat too. A portable one could be peazip)

The document list of the original source is as follows (others may be added in the future by various devs):

OHM Master & Subdocs (folder): This contains the OpenOffice.org (OO) files that contain the source text; however, while the Master Document (which combines all the chapters into one build) is in OO's native format, the subdocuments are in Word 97 format, so each should be openable in WORD 97 and later. (They are also openable in WordPad, but you shouldn't edit in this format as they will not retain all of the layout settings.) The Glossary is also in this folder in OO's native format.
>   MPT OHM Images (folder): Within the Subdocs folder are the images that are used in the chapters. MAKE SURE THIS STAYS IN THE ROOT LEVEL OF THE SUBDOCS. Otherwise the images may not appear (which may not be a problem if you only wish to edit the text). There may be a problem with the subdoc's link system -- see below for more info.
>>     Image Sources (folder): Within the Images folder are some images that are composed of layers in either PSD format (Photoshop) or XCF (GIMP). If you are editing or updating the images, check with these and edit the layers so you don't have to re-create the images. (Not all of the document's graphics have layered counterparts in this folder.)
MPT Research (folder): Within this folder are the various sources of info (mostly third-party) i used to learn how everything worked in MPT. These are presented here for verification of the knowledge base that MPT relies on. I decided to put them together in the source release, so future editors/translators would not have to go looking all over the internet for the pertinent data. This folder contains subfolders and a variety of files that went into the making of the OHM, including my own test results.
MPT OHM 1.0 & Glossary (PDF): The original build of 1.00. This document is included to give editors and translators an idea of the intended layout. Of course, you are free to create your own layout, even making no changes to the graphics or text, but this file gives an idea of how the original OHM looked. (OHM Updates will be added to this sourceforge folder for download.)
Miscellaneous help files (TXT or RTF): The original source folder includes the following:
>   A .txt file that describes how to fix your registry if your computer won't open extension-assigned files with MPT automatically,
>   A .txt file that describes how to use "problematic" or complex VSTs with MPT (i've included notes for using Roland's "Orchestral" VSTi).

If you wish to make your own changes for inclusion into the trunk build, edit the individual subdoc and ask the devs for inclusion (unless of course you are a dev!). Also check the first post in this thread for more reminders on building your own version...

KNOWN ISSUE: There may be a major problem with viewing the graphics on your computer. All of the subdocs are LINKED to the images; they are not embedded like the PDF release. This is why you have to keep the Images folder in the same folder level as the subdocs. However, i could not set the links to be relative rather than absolute. This means that OpenOffice will expect to find the images from MY personal computer, not yours. I tried it with both WORD 97-2000 format (.doc) and OpenOffice 3.2.1 format (.odt), but neither would make the links relative. (If anyone has a way to fix this, please let us know...)
WORKAROUND: There are only two things you can do to get the images to show if they are not linking:
1. The easiest option -- create a set of folders on your own computer with this hierarchy, mimicking my computer:
"C:/Documents and Settings/Kelley/Documents/Text Files/MPTs Offline Help Manual/OHM Master & Subdocs"
and put the "MPT OHM Images" folder into the "OHM Master & Subdocs" subfolder. To make it easy to navigate to that folder if you should need to, put an alias of the Images folder into the folder where you are keeping the Subdocs (unless you want to just put all the subdocs into the "Master and Subdocs" folder)...
2. The worst option -- go thru EVERY image in EVERY subdocument and change the link to match that of your computer. Do this by double-clicking on the image to open the Picture dialog, click on the "Picture" tab, and edit the "File name" field. Count on about 4 hrs worth of work.
The reason we want to have the images linked rather than embedded is twofold. First, if changes need to be made in the future (and they undoubtedly will), you only have to change the image rather than the whole subdocument. Secondly, many of you might wish to transcribe the OHM into other file formats, like a Windows Help File or an HTML page. These formats use linked images as well, and make for much more easily buildable and editable documents.
With that said, you are free to build your own OHM from these documents and embed the graphics to alleviate the problems with linked graphics.

BTW, the documents are up-to-date for MPT 1.18.3, altho i have not built a PDF from it yet.

Note to devs: if you'd rather not have an archived source, you're welcome to disassemble the archive and put the files right there in the OHM folder at sourceforge. You may also delete any files you think are superfluous, the only ones i want to remain are the original .docs that make up the chapters and the graphics folder, so users can create their own versions easily.

[Saga Musix]

The archive is in RAR format, and requires WinRAR 2.9 or above (or a program that can de-archive RAR 2.9 files). That application is shareware but completely usable.

7-zip is free software and compresses the file much better (~30mb in the .7z format).

Good that the sources are out now, that's a good start for transferring all the text to a wiki, as soon as more important things are done.

[Harbinger]

Good to know. I do like 7Zip better anyway, it's much more flexible with archiving and de-archiving.