I'm going to start assembling the COMPLETE Help manual in an offline format (so that an internet connection is not required), using the few Wiki pages we have, and then going from my own experience. I will also be exploring the threads in these forums for info. Some of you may have already written your own tips that you've never been able to format into the Wiki or elsewhere. If you e-mail me what you have or provide a link if it's not in these forums or in Wiki, i will include your tips and how-to's in the manual.
I'm a pretty good technical instruction writer, and i'd like to make it easier for new users to dive right in. I use MPT exclusively and i'm not getting bored with composing, so i can maintain this manual continuously. I intend to submit sections to our esteemed devs to make sure the info is correct, but once verified, i will post the text here, and everyone can pitch in with corrections to the guide, or additional information that will help any MPT user in a particular subject. The guide will be image-rich!
I'll keep you aware in this thread of Offline Help Manual changes or developments, and you can make any comments here as we go. Please, no threadjacking!
Here's the proposed outline:
1. What is ModPlug Tracker?
2. System Setup
System requirements
Expandibility
Portability
3. MIDI input/output setup
Using an external MIDI keyboard
MIDI output through VSTi's
4. Basics of tracking
What is tracking?
Difference between tracking and sequencing
5. Basics of ModPlug Tracker
Overview of the tracking interface
MPT features
6. General setup
Audio setup
Display setup
Key entry Setup
Channel Setup
Other options
Song-specific settings
7. Using Samples
What are samples, and where do i get them?
Can I alter the samples in MPT?
Importing samples
Sample attributes
Assigning samples to instruments
8. Using Instruments
The difference between samples and instruments
How are instruments used in MPT?
Importing instruments
Instrument attributes
Using VSTi's
9. All about Patterns
What are patterns in MPT?
Creating a pattern
The Pattern display
Using the Pattern Order box
The Pattern Editor
Entering data
Navigating
Playback
Note events
Instrument designation
Note FX
Channel FX
All about macros (Zxx)
10.Saving modules
11.Exporting audio files
Exporting with MPT
.wav files
.mp3 files
Sharing files
12.MPT's formats
.mod
.s3m
.xm
.it
.itp
.mptm
.mid
Other readable formats
13.VSTs
What are VST Effects?
What are VST Instruments?
Importing and applying VSTs
VST problems and limitations with MPT
14.Tunings
What are tunings and when do I need them?
Creating tunings
Applying tunings
Tuning issues
15.Appendix A: FX commands
.mod commands
.s3m commands
.xm commands
.it commands
.mptm commands
16.Appendix B: MIDI commands
17.Reference: Menus
File
Player
Edit
View
Window
Help
18.Reference: Dialogs
General Setup
Song Properties
Plug-in Setup
Channel Manager
MIDI mapping
Tuning Properties
Amplify Options
Macros Configuration
Chord Editor
19.Reference: Tabs
General
Patterns
Samples
Instruments
Comments
20.Known Issues
I hope you do not considering this threadjacking, but I think it would be a better idea to update the Wiki. In the Wiki there are options to print or export to HTML, PDF, RTF or XAR which I think covers the offline options (an offline guide could easliy be compiled from the Wiki).
Other than that, great initiative!
No, a proper updated help file in offline format included with the installation files would be a great help for new MPT users and other who want a quick access to the help files.
I'd like off line help too - my music computer is not on the net
Quote from: "g"I hope you do not considering this threadjacking, but I think it would be a better idea to update the Wiki. In the Wiki there are options to print or export to HTML, PDF, RTF or XAR which I think covers the offline options (an offline guide could easliy be compiled from the Wiki).
Other than that, great initiative!
No, this isn't threadjacking. This has every bit to do with the subject at hand. 8)
Concerning the online issue, i'm not on the internet at home, which is my impetus for making this. I want new users to be able to use the help button if they're stuck, without having to be online.
Also, i do not know the Wiki syntax (and i won't be trying to learn), so i won't be doing that. Once (or perhaps AS) everything is written up and posted, someone who can, can post it in the Wiki page, which can be used if an MPT user is online.
I wonder what the offline help should look like if you're not even willing to learn the wiki syntax (which is very simple) - raw .TXT?
Actually, I'd prefer if there weren't so many documents at all, but rather one big (like the wiki) which can be exported into many formats - for example for offline reading.
Use the windows help file system, with chm extension. Here is a software to compile these help files:
HTML Help Workshop and Documentation
https://www.microsoft.com/downloads/details.aspx?familyid=00535334-c8a6-452f-9aa0-d597d16580cc&displaylang=en
http://en.wikipedia.org/wiki/Microsoft_Compiled_HTML_Help
Quote from: "Jojo"I wonder what the offline help should look like if you're not even willing to learn the wiki syntax (which is very simple) - raw .TXT?
Actually, I'd prefer if there weren't so many documents at all, but rather one big (like the wiki) which can be exported into many formats - for example for offline reading.
As i'm writing, i'll just use WORD format, as it's second nature to me. There will be lots of links (between chapters especially) and lots of images, which both WORD and our forum's BBCode can handle.
After that, if anyone wants to translate to HTML (which i'm asserting now, will NOT be me), i can make the original .doc or the original BBCode available to them for translation.
Word can save as HTML - not sure how good the html is - but it is a possible route.
The wiki also has a tutorial. You should add it to the manual. :)
uncloned: Putting "HTML" and "Word" in the same sentence is just... wrong. Microsoft HTML generators tend to output the worst HTML that I've ever seen.
Quote from: "Jojo"Putting "HTML" and "Word" in the same sentence is just... wrong.
:lol:
Quote from: "Jojo"uncloned: Putting "HTML" and "Word" in the same sentence is just... wrong. Microsoft HTML generators tend to output the worst HTML that I've ever seen.
but would it not be closer to the desired final product?
- what about open office - can it do html?
It can certainly import Word files with flying colors
Not sure if OOo can do it (but if it can do it, the HTML would look much better with no doubt, because it wouldn't use proprietary M$ elements), but it can export to PDF at least, which is also nicht - but it's not as convenient for manuals because searching is more difficult and I don't think that you can call PDFs "dynamically" (with jumping to the correct chapter etc) from an external app like modplug.
pdf - yes that is a good option. It preserves Harbinger's work and is a portable monolithic format.
Multiple formats is always an option. One format for the "in program" help file. And one format (pdf?) for off program purposes.
You don't really want to do this manually, do you...?
For plans like this, you need a good program to start with.
To be honest, I think that the best option would be LaTeX. It's got probably the simplest syntax of all the text-based formats (HTML, bbCode, Wiki, etc), produces beautiful output, and is universally usable.
Oh sure, LaTeX is great. Now let's convince Harbinger to learn LaTeX! ;D
Is there not some way to convert from Word? Its only data...
It's only data that Microsoft doesn't want to be edited in non-M$ products. Therefore, it's just as cryptic as possible. :P
But nonM$ programs like open office can access the data. Once there you have no M$ limitations, no?
if a Word to RTF to LaTex converter doesn't exist it would seem to need to, no?
Quote from: "bvanoudtshoorn"To be honest, I think that the best option would be LaTeX.
You must be kidding :)
Quote from: "Relabsoluness"Quote from: "bvanoudtshoorn"To be honest, I think that the best option would be LaTeX.
You must be kidding :)
Why? LaTeX is a beautiful piece of software. At Uni, I wrote all of my honours year assignments in CS using it. :)
IF you are going to write it on a 'word' type program, try open office or some other program that has pdf export like abiword. You can use a program like Wikidpad to your benefit as well. CHM is a good option too. A program called KeyNote may be good for you as well.
I think the issue is that Harbinger doesn't want to learn a new program - considering he's doing the work we probably would be wise to accommodate him somehow. IMHO anyway
IF the wiki can export in HTML I can get the CHM created. Or one of these other fine people can as well.
An excellent initiative,
Harbinger !
Having connection or not, I far prefer to have off-line services like a help file.
And the proposed outline is a very thorough thinking..
I don't mind much about the ways to compile the data into a destination. Several tools are possible.
If you prefer to get the base material from a clumsy Word construction, fine by me.
I think more about the different kinds of output :
1. CHM - the current default replacement for the ole *.hlp
2. PDF - need an external reader installed.
3. HTML - could be offline used with the browser
QuoteThe guide will be image-rich!
So an important aspect concerning efficiency, because images take lotsa space.
With a PDF they are included, so the file gets big.
With HTML the bitmaps are in a subdir.
I'm not sure about CHM, whether screenshots are included in the file or not.
It's also an item, which format is the easiest to update with new data ?
So it's more smooth to have a package of elements, script-files, visual files, maybe even sound files.
It will be more simple to replace a certain screenshot by a better one, while the rest stays the same.
one thing that helps with images is to reduce the number of colors to aid with compression - for something like a guide to a program 256 colors should be ample - the illustrations are akin to a cartoon.
Good point. I do this a lot to reduce filesize. Some screenshots easily stay well with 16 colors.
A nice tool to check this is RIOT (http://www.louigiverona.com/webarchive/samzen/download/riot032.7z)
There's PNGOUT tool, it can significantly reduce the size of png images with no quality loss :D
Greyscale PNGs or JPEGs? They may offer lower sizes as well, and less colors to deal with.
I would suggest just outputting the html, or word doc, handing it off to someone else for the pdf and chm creation. I just got that chm workshop tool, and have pdf printers on my computer. Others must have them as well.
If the word doc doesn't require actual Word to run I can load it as well.
Quote from: "Nahkranoth"There's PNGOUT tool, it can significantly reduce the size of png images with no quality loss :D
hell yes. PNGOUT for the win. Don't reduce colors with modplug screenshots, DON'T use jpeg or gif - use png together with pngout.
Quote from: "bvanoudtshoorn"Why? LaTeX is a beautiful piece of software. At Uni, I wrote all of my honours year assignments in CS using it. :)
What would be the aspects where LaTeX beats, say, HTML documentation in the context of OpenMPT documentation? Things like ease of writing mathematical text isn't very relevant now, while for example ease of using images is. And in any case people most involved in the work likely have no experience on using LaTeX and are perhaps even less interested to use time to learn it, and that takes a bit more than learning a couple of simple commands.
Quote from: "Jojo"I don't think that you can call PDFs "dynamically" (with jumping to the correct chapter etc) from an external app like modplug.
Good point; having a dynamic help in OMPT might come topical at some point.
Quote from: "Relabsoluness"Quote from: "bvanoudtshoorn"Why? LaTeX is a beautiful piece of software. At Uni, I wrote all of my honours year assignments in CS using it. :)
What would be the aspects where LaTeX beats, say, HTML documentation in the context of OpenMPT documentation? Things like ease of writing mathematical text isn't very relevant now, while for example ease of using images is. And in any case people most involved in the work likely have no experience on using LaTeX and are perhaps even less interested to use time to learn it, and that takes a bit more than learning a couple of simple commands.
Well, if someone gives me HTML or Word source, I'm happy to convert it to LaTeX.
The advantages of LaTeX are manifold.
Advantages over Word/OO.o:1. Simple diagram referencing
2. Simple index / TOC creation
3. Editable by *anyone* with *any* computer
4. Clean and simple pdf links
Advantages over CHM/HTML:1. Simple diagram referencing
2. Simple index / TOC creation
3. Output that is equally beautiful on-screen or in print (you can even specify different output settings and produce multiple documents from a single source file -- this way, we could, for example, have a screen-optimised version, a US Letter version, an A4 version, and a quick-reference version that only prints certain sections.)
The weekend is here, so i'm now online again. I see there's been a hearty debate without me. :D
I'm about 25% done (there's a LOT to cover!), and i'm using OpenOffice (which i despise :x ), but i keep telling myself "it's only temporary...."
I think the best course of action just may be that i should simply submit the file as is (or email to those who request), and let those who can convert it, do so and submit their work. This way anybody can get a version they prefer -- .chm HELP file, .pdf (which i can do, that's easy), or LaTeX, or whatever format. This would be in keeping with the open spirit of today's MPT, and give the user even MORE flexibility.
I would then submit a request to the devs to provide the user with an option to declare a path to the help file of their choice either offline or online (in the same way the VST paths are customized). My dream is to one day click on the help icon, and get an old-fashioned Help manual that i can keep in the background. 8)
I dunno, but if you haven't used the fugly Office 2007 before, OOo isn't really much different to MS Office...
Nice suggestions, Harbinger.
UPDATE....
60%-70% done with the "beginner's section". (The highly technical Reference section will be later.)
Am now working on the Pattern page -- the last major section. Lots of details.
I've decided to format it for PDF reading, because i need all the images in specific locations on the page to help with visuals.
Nice to hear Harbringer! Looking forward to see the help-file when it gets published.