Draft MCX manual

arno

Administrator
Staff member
FSDevConf team
Resource contributor
Hi all,

In preparation of the next stable release of MCX I have been working on a new user manual. From today the development release does include a draft version of this manual.

I haven't finished all sections yet, so some parts are missing. But all editors, wizards and tools are described. So hopefully this draft is useful already. And I hope to have the rest finished soon as well.

Feedback on items that you would like to have included in the manual are always welcome!
 

tgibson

Resource contributor
Hi,

Some minor things:

There don't seem to be any tutorials on how to create certain popular features, including hardened platforms (hidden within the Attached Object Editor - not obvious), creating PBR materials, etc. These could expand chapter 3.

4.3 "In the options form you get set all the options of ModelConverterX." could be "In the options form you set all the options of ModelConverterX. "

"With the Reset to default button in the toolbar at the top of the form you can reset the currently
selected category of options to their default values. With the Reset all to default button you
can reset all options categories at once to their default values."

could be:

"The Reset to default button in the toolbar at the top of the form resets the currently
selected category of options to their default values. The Reset all to default button
resets all options categories at once to their default values."

4.3.x Have an odd format; could have a layout that would be easier to understand. EDIT: I think these will be formatted later?

Example:
Current layout:
===== AutoSave =====
The AutoSave section allows you to specify settings regarding automatically saving certain files.
It contains the following options:
; AutoSaveEventLog : Determines whether the event log is automatically saved to disk as a TXT
file when you export an object. ; AutoSavePreview : Determines whether the preview image is
automatically saved to disk as a JPG file when you export an object.

Better layout?
AutoSave
The AutoSave section specifies settings regarding automatically saving certain files.
It contains the following options:
AutoSaveEventLog : Determines whether the event log is automatically saved to disk as a TXT
file when you export an object.
AutoSavePreview : Determines whether the preview image is
automatically saved to disk as a JPG file when you export an object.

Note: I usually think that manuals are better in the third person (i.e. "specifies settings") rather than 2nd person ("allows you to specify settings"). This is a personal preference and one you do not have to agree with. :) I will no longer suggest those changes below, but there are others.

4.3.1 "MaximumUndoMemory: The amount of memory (in MB) that
can maximum be used by the undo functionality. If more memory is used the olders steps will be
removed and can not be undone anymore."

could be:

"MaximumUndoMemory: The maximum amount of memory (in MB) that
can be used by the undo functionality. If memory needed for undo exceeds this value the older steps will be
removed and can no longer be undone."

"CheckForUpdateUnstable" could instead be "CheckForUpdateDevelopment" (a change in MCX). Unstable sounds so scary. :)

4.3.2 Particles - isn't this really an Effects section, since PlaySounds has little to do with particles. (This would be a change in MCX.)

"ZoomScale" could be "MouseZoomScale" which would make it clearer what it does. (MCX change).

4.3.3 "Create empry LOD" should be "Create empty LOD"

4.3.5 "This should be false for FSX DDS files." Isn't this also the case for P3D DDS files?

"The texture is first searched in the folder of the object you are reading, after that all folder in the search path will be examined. " should be "after that all folders"

"You can use the special tags [FS2004] and [FSX] to entire paths depending on your FS installation folder." This is unclear, perhaps you mean "You can use the special tags [FS2004] and [FSX] to specify the path to your FS installation folder." And there is no such tag for P3D?

4.3.6 "Having a small offset can give noise at lower mipmaps." Could this mean "Having a small offset can cause edge artifacts at lower mipmaps."

More later.
 
Last edited:

arno

Administrator
Staff member
FSDevConf team
Resource contributor
Hi Tom,

It's chapter 5, 6 and 7 that are ready. Chapter 4 is still in progress.
 

arno

Administrator
Staff member
FSDevConf team
Resource contributor
Hi Tom,

Good suggestions for topics to address in chapter 3. I have added them as reminders in there.

I have also taken over some of the spelling/grammar suggestions. The section about the options is still from the old manual, that needs a big update.

Instead of posting all kind of sentence suggestions here, I can also send you the manual files later to try to remove some of the Dutch-English sentence constructions :)
 

tgibson

Resource contributor
Hi,

These were written before you posted; it would be fine to send me the draft when completed, assuming I have an editor that can accept such documents (I do not have Adobe Acrobat).

More:

4.4 It would be helpful if this section contained some information on the various types of errors: Warning (not necessarily a problem), Error (compile will fail), etc.

4.5 "If there is no icon the event log is empty, but if there are entries in the log the following icons can be displayed:" There are no icons described.

5.1 "The scenery object editor gives an overview of all the objects in the current scenery, see 5.1." These figure references early in chapter 5 include only the number. Later they instead refer to "Figure 5.5". This makes it clearer what you are referring to, so it might be a good idea to make all such references similar to "see Figure 5.5".

Question - When pressing the Add button how is the GUID assigned for FS2004 models, which do not contain such a GUID in the model itself?

5.2 "Bounding box minimum and maximum values for each axis" - it might be helpful to mention that these are editable using the MDL Tweaker, if needed?

5.4 "With the Remove button you can delete the currently selected node(s) from the object. While
with the Isolate button only the currently selected objects are retained and those will be used as
the new object."

Sentence fragment. Could be:

"When the Remove button is pressed you can delete the currently selected node(s) from the object.
When the Isolate button is pressed only the currently selected objects are retained and those will be used as
the new object."
 

tgibson

Resource contributor
5.4 I think it might make more sense to place Figures 5.7 and 5.8 after the Transformation paragraph instead of within the Animation paragraph.

5.5.1 The default for the detail texture is "detail", not bump.

5.5.2 "The drawcalls tabs, see Figure 5.15" should be "The Textures tab, see Figure 5.15".

Figure 5.16 could be placed earlier, immediately after the Save Textures paragraphs.

5.7 "Using the textbfSelect invert button" I assume this should be Bold instead.

5.8 "Edit mode button to toggle edit more." Should be "edit mode".

6.2 "because the different textures have not bee layered correctly" should be "been", not "bee".

"See section 10.1" I understand that you are using this to specify a specific part of a chapter, but you are also using the word "section" to describe parts of forms. Perhaps "subchapter" or "chapter section" might be better?

6.4 "how many placements have been skipped before the referenced object could not be found." Could be "because" not "before".

7.16.3 "See Figure 7.10 for an example of a smooth shaded object." should be "See Figure 7.10 for an example of a flat shaded object."

8.1 The figure (Table 8.1) is not referenced in the first paragraph. The Table does not include the FS2004 object reader.

8.1.3, 8.1.4, 8.2 The formatting should be converted to bullets, as present in 8.1.2

8.1.4 "sectionBGLComp BGL reader" I assume this should become a header for another section of this chapter.

10.2 "Intrinsic Extrinsic" I'm not sure what these are.

10.3 "Of course one test is not full proof" Should be "fool proof", not "full proof".

11.1, 11.2 "If you have any problems while using scenProc" Both paragraphs should be ModelConverterX, not scenProc.

Hope this helps,
 

arno

Administrator
Staff member
FSDevConf team
Resource contributor
Hi Tom,

Thanks for the useful feedback, I'll have a look at the various suggestions.

It would be fine to send me the draft when completed, assuming I have an editor that can accept such documents (I do not have Adobe Acrobat).
The manual is written in LaTeX, so the source files with the text are just plain text files that you can view in Notepad or so.

I keep these manual source files together with the source files of MCX. That why it becomes a lot easier to update the manual when I make changes. I'm doing this with scenProc for a while now and it works much better than a manual on the wiki. When the development release is build, the PDF manual is automatically created from these LaTeX sources as well.

4.4 It would be helpful if this section contained some information on the various types of errors: Warning (not necessarily a problem), Error (compile will fail), etc.
Good idea, people often think a warning is a big problem already.

Question - When pressing the Add button how is the GUID assigned for FS2004 models, which do not contain such a GUID in the model itself?
Internally in MCX it is still assigned. If you export to BGL it will stick, if you export to MDL it does not matter indeed as the GUID is not stored there.

5.2 "Bounding box minimum and maximum values for each axis" - it might be helpful to mention that these are editable using the MDL Tweaker, if needed?
The MDL Tweaker is to edit the MDL file directly. Don't you think it is confusing here to mention you can edit them there? I mean, if you edit them in the MDL Tweaker they would still display the same in the object information form. As these values are calculated from the model.

5.4 I think it might make more sense to place Figures 5.7 and 5.8 after the Transformation paragraph instead of within the Animation paragraph.
LaTeX chooses automatically where to put the figures, to prevent half empty pages. So if there is not enough space to put them directly below the text, they go to the next page.

"See section 10.1" I understand that you are using this to specify a specific part of a chapter, but you are also using the word "section" to describe parts of forms. Perhaps "subchapter" or "chapter section" might be better?
Maybe I should not use section when I refer to forms. I don't think I do that very often, let me check.

10.2 "Intrinsic Extrinsic" I'm not sure what these are.
That's why I plan to write a section in the background information chapter about them :)
 

arno

Administrator
Staff member
FSDevConf team
Resource contributor
The next development release, that should be online in about 15 minutes, includes an updated manual. I have processed the feedback from @tgibson and I have finished the chapter about the user interface now. I have also marked the chapters that are still WIP more clearly now.
 

arno

Administrator
Staff member
FSDevConf team
Resource contributor
The download link in the resource section still works:


Yesterday the site was down for a few hours, it seems that has done some damage to the wordpress site.
 

arno

Administrator
Staff member
FSDevConf team
Resource contributor
Hi,

The scenerydesign.org website has been fixed now. Due to the issues with the website the new development release did not upload correctly last night as well. So I'm pushing a new build and hopefully it's online in about 30 minutes.
 

tgibson

Resource contributor
I looked over Chapter 4 (User Interface) and it looks fine to me. There are a few typos (at least two "you" should be "your"), but they are minor.
 
Top