[edwardk]

Important note: The Documents button will be disabled if the Documentation folder is not present or if present and empty.

Edward K.

[Genma Saotome]

Sid P., on 17 December 2015 - 02:15 PM, said:

Some thoughts:
Since the Manual is presented in a PDF (or Doc) viewer with all of the sub headings available in the "navigation" or "view" panel, I don't feel that much is to be gained by adding more levels to the "Table of Contents" page in the document itself.

And for a contrary opinion, IMO the present level of indexing is woefully inadequate. Chapter 8: Open Rails Physics, is 50 pages long and has it's first page in the ToC and that is it. Timetables are about the same.

[James Ross]

edwardk, on 17 December 2015 - 12:06 PM, said:

Keep in mind James that developers also need easy access to documentation. Thanks for the disabling the button tip. This was something I was not thinking about.

I think developers will have no problem opening the source documents from Source\Documentation, unlike normal users and supporters/content creators.

edwardk, on 17 December 2015 - 02:10 PM, said:

As of V3392, the feature to allow immediate access to documentation was added on the menu. If you are running the stable version, the Documentation folder will be present, but not present with the experimental versions that are downloaded. This folder can be found under the source directory if you are downloading via TortoiseSVN.

I thought you were going to make a test build first, but never mind; thanks for implementing this. Can you update the blueprint?

• Please put the blueprint in the commit message next time - they are the cross-reference point, not the forum thread.
  
• The use of "Directory.GetCurrentDirectory()" is not good - it could literally be set to any directory. Please use the same code as the tools does above, using "Application.ExecutablePath".
  
• There is no need to support anything other than ".pdf" so please remove the other types.
  
• It's probably easier to update the enabled state after doing the loop based on "contextMenuStripDocuments.Items" - if there are menu items, enabled, otherwise, disabled. That way there's no weird cases of having a "Documentation" folder but no supported formats, for example.
  
• The function "CheckForDocumentation()" doesn't seem to be used and has no code inside it. Remove it.

[Csantucci]

I have a request on this useful feature: the "Documentation" subfolder is not created when using the "Unstable" update mode, and this is OK. But I would prefer that a "Documentation" subfolder, created with the "Testing" update mode, not to be deleted when passing to the "Unstable" update mode, so that documentation would still remain easily reachable also with this latter update mode. Maybe it won't be last version, but people using the "Unstable" mode may be made aware of this.

[James Ross]

Csantucci, on 19 December 2015 - 12:06 AM, said:

I have a request on this useful feature: the "Documentation" subfolder is not created when using the "Unstable" update mode, and this is OK. But I would prefer that a "Documentation" subfolder, created with the "Testing" update mode, not to be deleted when passing to the "Unstable" update mode, so that documentation would still remain easily reachable also with this latter update mode. Maybe it won't be last version, but people using the "Unstable" mode may be made aware of this.

Interesting, we might be able to do that. It's tricky though as we do need to delete the directory for Stable and Testing updates to ensure no old documentation is left behind.

[Sid P.]

Genma Saotome, on 17 December 2015 - 04:45 PM, said:

And for a contrary opinion, IMO the present level of indexing is woefully inadequate. Chapter 8: Open Rails Physics, is 50 pages long and has it's first page in the ToC and that is it. Timetables are about the same.

OTOH, I agree with you when considering a "printed" copy of the Manual - I am of an age that I personally still prefer to study a document in a hand-held form! I have a booklet size version next to my terminal right now. If there is a need for a printable version, then a fuller Table of Contents and a real Index would certainly be of great benefit.

Cheers,

[Genma Saotome]

Sid, I'm willing to do the work to extend the ToC, at least to one more level, if you want.

Something else... sometime ago I asked if were possible for the OR software to send html to a handheld device and James said yes it was. One of the things that eventually could be done with that idea is to present a small section of the documentation (or one that's extensively hyperlinked from both ToC and index). This makes me wonder about distributing html instead of .doc files. Any thoughts on that?

[James Ross]

Csantucci, on 19 December 2015 - 12:06 AM, said:

I have a request on this useful feature: the "Documentation" subfolder is not created when using the "Unstable" update mode, and this is OK. But I would prefer that a "Documentation" subfolder, created with the "Testing" update mode, not to be deleted when passing to the "Unstable" update mode, so that documentation would still remain easily reachable also with this latter update mode. Maybe it won't be last version, but people using the "Unstable" mode may be made aware of this.

Turned out to be really easy, so this is now enabled in X3402. Because the updater used is always the current (not new) one, you won't see the change for real until you've updated to the next Testing Version on Friday and then switch to Unstable. However, if you update to Unstable Version X3402 now and create a Documentation folder (e.g. by copying from the Unstable Version), it should persist when you update to the next Unstable Version (no matter what you put in it). Just be aware that as soon as you update to a version that has Documentation, the entire folder is deleted and replaced.

[Sid P.]

Genma Saotome, on 19 December 2015 - 10:22 AM, said:

Sid, I'm willing to do the work to extend the ToC, at least to one more level, if you want.

Dave, that would be great. Please contact Carlo (Csantucci) and me via PM regarding passing and exchanging file versions.

Quote

Something else... sometime ago I asked if were possible for the OR software to send html to a handheld device and James said yes it was. One of the things that eventually could be done with that idea is to present a small section of the documentation (or one that's extensively hyperlinked from both ToC and index). This makes me wonder about distributing html instead of .doc files. Any thoughts on that?

I don't have extensive experience at creating larger .html documents, so I don't know the extent of the effort involved. What are the tools available? I have Expression Web 4.

Cheers,

[Csantucci]

James Ross, on 20 December 2015 - 03:02 AM, said:

Turned out to be really easy, so this is now enabled in X3402. Because the updater used is always the current (not new) one, you won't see the change for real until you've updated to the next Testing Version on Friday and then switch to Unstable. However, if you update to Unstable Version X3402 now and create a Documentation folder (e.g. by copying from the Unstable Version), it should persist when you update to the next Unstable Version (no matter what you put in it). Just be aware that as soon as you update to a version that has Documentation, the entire folder is deleted and replaced.

James, thanks for that :)