[
https://issues.apache.org/jira/browse/ISIS-1307?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Dan Haywood updated ISIS-1307:
------------------------------
further discussion between Dan and Steve:
Dan:
> With respect to a user manual, I was mostly thinking in terms of some sort
> of overlay that would render a help page for the current object.... a bit
> like how in gmail pressing "?" will pop up shortcut keys. The viewer could
> search for an associated file, eg Customer.adoc (similar to how it searches
> for Customer.layout.xml or Customer.png), and if present, pass the .adoc
> through a rendered to generate HTML to be shown in the overlay.
>
> This could also be used as an extended tooltip for individual object
> members, eg Customer#placeOrder.adoc etc.
>
> Thoughts?
>
Steve:
Having the same approach as tor the layout.xml would be good, and to be
able to similarly generate a whole set of .adoc files even better.
At the moment I have one .adoc file for each class but they are all in one
folder. That was to make it easy to create a user 'manual' . I have a
book.adoc in the same folder that has lots of import::fileXYZ.adoc
statements, this seems to be the only way to create your desired ordering
of sections in the book, via the sequence of imports.
I also make use lots of links to minimise duplication of information. So, I
think in any system implemented its desireable that, after opening a help
page via "?" to get to contextual info, you can then browse further va
links (to be in an iframe essentially).
Inside each class adoc file I create BlockIds using the [[ClassName]] (at
the start) and [[ClassName__methodName]] conventions, I think there was an
issue with using only legal characters in the Id. Creating a hyperlink is
usually then <<ClassName, ClassName>> as you know.
Maybe to use a fully qualified class name is not such a big issue to ensure
uniqueness of keys. You can do a global search and replace after writing a
page, looking for the [[ and << markers to know where to add in the missing
path.
Once you've done that the Isis help system should be able to find the
relevant method or property block to display within a single class adoc
file, rather than having lots of files, or if its been converted to HTML
its trivial to identify the HTML Id to use in a internal URL.
> Integrating User Help Documentation
> -----------------------------------
>
> Key: ISIS-1307
> URL: https://issues.apache.org/jira/browse/ISIS-1307
> Project: Isis
> Issue Type: Improvement
> Components: Core
> Reporter: Steve Cameron
> Assignee: Dan Haywood
> Priority: Minor
> Fix For: 1.16.0
>
>
> At the moment there is the @PropertyLayout#describedAs() attribute for
> providing help 'hints' to users. I am wondering if there could be added a
> more detailed help information being provide to a user pressing F1 key?
> More specifically to design a mechanism for help documentation to be
> navigated to (into) from the Isis Wicket viewer interface in a context
> sensitive way.
> Broadening this further still, maybe there is a good way to keep user
> documentation embedded within the Java domain object class files and to
> generate formatted user help documents in a similar way that Javadoc is
> generated?
> I've done a little research on this approach but cannot find an example of
> where this has been done, but to my mind it seems natural as a Naked Objects
> way to do it.
--
This message was sent by Atlassian JIRA
(v6.3.4#6332)
