From 7419e124391aa6081fedb799c7fc2a12aa6d864a Mon Sep 17 00:00:00 2001 From: Jonatan Liljedahl Date: Sun, 8 Jan 2012 15:29:07 +0100 Subject: [PATCH] Quark: use \schelp for new help, and open category browser for quark if not given. The old \helpdoc is used if there are no new help in the quark. This allows quarks to support both old and new help during the transition to the new help system. (cherry picked from commit 05529e182f5b8825ea8050e9e488eb1d15b336df) --- HelpSource/Classes/Quark.schelp | 20 +++++++++------ HelpSource/Guides/WritingHelp.schelp | 5 ++-- SCClassLibrary/Common/Quarks/Quark.sc | 46 ++++++++++++++++++++--------------- 3 files changed, 41 insertions(+), 30 deletions(-) diff --git a/HelpSource/Classes/Quark.schelp b/HelpSource/Classes/Quark.schelp index 3b649b45d..4b7e2240d 100644 --- a/HelpSource/Classes/Quark.schelp +++ b/HelpSource/Classes/Quark.schelp @@ -27,7 +27,7 @@ code:: \organization: "My Organization", \country: "My Country", \since: "2004", - \helpdoc: "Classes/MyClass", + \schelp: "Classes/MyClass", \ext_dependancy: "Information on additional software needed to run this quark properly", \url: "http://www.strangeQuark.de", @@ -47,14 +47,18 @@ In most cases this is simply the name of the quark and also the name of the fold It may even be possible to nest quarks inside of quarks (a kind of aggregate package), though a better way to do that would be to define an empty quark (the aggregate) and specify the other sub quarks as dependencies. -The value of code::\helpdoc:: is a help path relative to an included teletype::HelpSource:: folder. -It is used as the main help file for the quark. (See link::Classes/Quark#-openHelpFile:: ) -For example, if the quark contains teletype::HelpSource/Reference/MyQuark.schelp:: one would use: +The value of code::\schelp:: optionally sets the main help file for the quark. It is a help path relative to an included teletype::HelpSource:: folder. +For example, if the quark contains teletype::HelpSource/Reference/MyQuark.schelp:: one could use: code:: - \helpdoc: "Reference/MyQuark" + \schelp: "Reference/MyQuark" :: +It is used by link::#-openHelpFile::. If no code::\schelp:: is given, it will open the category browser showing all helpfiles for the quark. -note:: Please test that you don't have any syntax errors in your quark file before commiting it.:: +note:: +The old help system (sc version 3.4) used code::\helpdoc::, and the new help system (link::Classes/SCDoc::) uses code::\schelp:: instead to be able to support both old and new helpfiles during the transition to the new help system. +:: + +warning:: Please test that you don't have any syntax errors in your quark file before commiting it.:: classmethods:: method:: find @@ -74,5 +78,7 @@ The path of the quark. method:: info The whole info blob as given in the .quark file. method:: openHelpFile -Open the main helpfile for this quark. +Open the main helpfile for this quark as given by the code::\schelp:: key in the directory file, +or the category browser page showing all helpfiles for this quark if no main helpfile was specified. +This method falls back to opening the old help as given by code::\helpdoc:: if above fails. diff --git a/HelpSource/Guides/WritingHelp.schelp b/HelpSource/Guides/WritingHelp.schelp index 7b793db43..1cae1b305 100644 --- a/HelpSource/Guides/WritingHelp.schelp +++ b/HelpSource/Guides/WritingHelp.schelp @@ -233,7 +233,6 @@ Each extension should have their own HelpSource folder with files that should be Example file layout: code:: -MyQuark/HelpSource/Quarks/MyQuark.schelp MyQuark/HelpSource/Classes/MyClass1.schelp MyQuark/HelpSource/Classes/MyClass2.schelp MyQuark/HelpSource/Guides/MyGuide.schelp @@ -242,10 +241,10 @@ MyQuark/MyClass1.sc MyQuark/MyClass2.sc :: -In the Quark directory file, set code::\helpdoc:: to the path relative to teletype::HelpSource:: and without the teletype::.schelp:: extension. Example: code::\helpdoc: "Quarks/MyQuark":: - All helpfiles contained in a quark will automatically get a category "Quarks>NameOfQuark" added, so you should not add this yourself. This makes it easy to navigate all documentation of a specific quark. +If you want to set a main help file for the quark, set code::\schelp:: in the Quark directory file to the path for the help file relative to teletype::HelpSource:: and without the teletype::.schelp:: extension. Example: code::\schelp: "Guides/MyGuide":: + subsection:: Method extensions An extension that adds methods to existing classes should document these in code::Classes/TheClass.ext.schelp::, only including the relevant bits (no title, summary, categories, etc..) diff --git a/SCClassLibrary/Common/Quarks/Quark.sc b/SCClassLibrary/Common/Quarks/Quark.sc index 789182036..aa4085b7e 100644 --- a/SCClassLibrary/Common/Quarks/Quark.sc +++ b/SCClassLibrary/Common/Quarks/Quark.sc @@ -132,19 +132,28 @@ Quark ^deps; } openHelpFile { - var p = info.helpdoc; - if(p.isNil) { - ("No primary helpdoc listed for Quark"+name).inform; - ^nil + var p = info.schelp; + if(p.notNil) { + HelpBrowser.openHelpFor(p); + ^this }; - case - {p.endsWith(".html")} { - HelpBrowser.goTo(HelpBrowser.getOldWrapUrl(parent.local.path +/+ path +/+ p)) - } - {p.endsWith(".scd") or: {p.endsWith(".txt")}} { - HelpBrowser.goTo(parent.local.path +/+ path +/+ p) - } - { HelpBrowser.openHelpFor(p) }; + if(File.exists(parent.local.path +/+ path +/+ "HelpSource")) { + HelpBrowser.openBrowsePage("Quarks>"++name); + ^this; + }; + p = info.helpdoc; + if(p.notNil) { + case + {p.endsWith(".html")} { + HelpBrowser.goTo(HelpBrowser.getOldWrapUrl(parent.local.path +/+ path +/+ p)) + } + {p.endsWith(".scd") or: {p.endsWith(".txt")}} { + HelpBrowser.goTo(parent.local.path +/+ path +/+ p) + } + { "Uknown help file type: %".format(p).warn }; + ^this + }; + HelpBrowser.openBrowsePage("Quarks>"++name); } printOn { arg stream; stream << "Quark: " << name; @@ -294,21 +303,18 @@ QuarkView { } fullDescription { var window; - var helpdoc = quark.info.helpdoc; window = GUI.window.new(quark.name, Rect(100, 100, 400, 200)).front; - GUI.textView.new( window, Rect(4, 4, 392, 170 + (helpdoc.isNil.binaryValue * 22))) + GUI.textView.new( window, Rect(4, 4, 392, 192)) .font_( Font.sansSerif( 12 ) ) .resize_( 5 ) .autohidesScrollers_( true ) .hasVerticalScroller_( true ) .string_( quark.longDesc ) .editable_( false ); - if(helpdoc.notNil) { - GUI.button.new(window, Rect(125, 176, 150, 20)) - .resize_(8) - .states_([["Open quark help"]]) - .action_({ quark.openHelpFile }); - }; + GUI.button.new(window, Rect(125, 176, 150, 20)) + .resize_(8) + .states_([["Open quark help"]]) + .action_({ quark.openHelpFile }); } remove { [installButton, nameView, infoButton, srcButton].do(_.remove); -- 2.11.4.GIT