openoffice-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Kay Schenk (Confluence)" <conflue...@apache.org>
Subject [CONF] Apache OpenOffice Community > Application Help
Date Mon, 21 Oct 2013 23:06:00 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/en/2176/1/3/_/styles/combined.css?spaceKey=OOOUSERS&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
    <h2><a href="https://cwiki.apache.org/confluence/display/OOOUSERS/Application+Help">Application
Help</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~kschenk">Kay
Schenk</a>
    </h4>
        <br/>
                         <h4>Changes (1)</h4>
                                 
    
<div id="page-diffs">
                    <table class="diff" cellpadding="0" cellspacing="0">
    
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >* Reduce the amount of offline help
content and allow to expand to online sources <br>* Allow rich media in help files <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">
<br>h3. Migration to a New/Different System -- questions/challenges <br> <br>*
Current Help source files (*.xhp) are xml defined by xmlhelp.dtd (/main/xmlhelp/util) <br>and
utilize main_transform.xsl (same directory). How to migrate this content to a new system.
<br>(some preliminary  testing has been done renaming *.xhp files to *.xml and using
the stylesheet to ascertain what this does exactly.) <br>* How would current indexes
be generated? <br>* What application changes would need to made to accommodate this?
<br></td></tr>
    
            </table>
    </div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <p>This is the planning page for the OO application help (aka online help, despite
not being "online").</p>

<h2><a name="ApplicationHelp-CurrentSituationandIssues"></a>Current Situation
and Issues</h2>

<h3><a name="ApplicationHelp-Structure"></a>Structure</h3>

<p>At present, the application help files are located in the source code module <em>helpcontent2</em>
with the following structure:</p>

<p><div class="code panel" style="border-width: 1px;"><div class="codeContent
panelContent">
<pre class="theme: Default; brush: java; gutter: false" style="font-size:12px; font-family:
ConfluenceInstalledFont,monospace;">
helpcontent2
   helpers           these are required or helpful for building the help content,
                     some files are called by make, some others are obsolete
                     xmlhelp.dtd  &gt; the DTD for the help XML format
   source            this is the actual content
      auxiliary      this are help relevant files that are not content
                     *.tree &gt; the definition files for the help viewer table of content
                     *.xsl &gt; transformation scripts used to process the help files
                     $LANG/*.css language dependent files for controlling the HTML output
                     $LANG/*.cfg language dependent config files (legacy)
      text           the help content files, organized by modules (rather awkwardly, see below)
</pre>
</div></div>The help content files are in a home-grown XML format described in
helpers/xmlhelp.dtd and are processed in various ways when the help is being built:</p>
<ul>
	<li>when non-English versions are built, the English content inside the help files
is replaced by the localized content stored in a different module.</li>
	<li>the help files are XSL-processed to produce the full text search index</li>
	<li>the help files are XSL-processed to extract the extended tips displayed in the
UI</li>
	<li>the help files are XSL-processed to extract the keyword index</li>
</ul>


<p>The final help set consists of sets of various files (jar, cfg, tree, xslt, database
files) for each module. A module in the help does not exactly correspond to an application
module (Writer, Calc, Impress) for historical and technical reasons. The schart module is
present in the help although there is no standalone Chart application. There is no sdatabase
module, although there is a Database application. So: it's a mess.</p>

<p>The biggest module is "shared" that takes all content that is valid for more than
one application (which is most of the content) in order to make it available to the help viewer
in all applications. But this leads to awkward side effects when content is valid for more
than one but not all applications, yet it is still available for all applications. This leads
to situations where the users finds content that is actually not in scope for his/her current
context (but still visible since in shared) which can be pretty confusing.</p>

<h3><a name="ApplicationHelp-Implementationwiththeapplication"></a>Implementation
with the application</h3>

<p>The <b>help viewer</b> is a Writer/Web component wrapped in a <del>nice</del>
UI and served by the help content provider. The appearance of the help UI is completely outdated,
and so are its concepts (to separate between TOC, Index, Search, for example), and the fact
that it's just a Writer document window in disguise can lead to all sorts of <del>funny</del>
nasty side-effects. Also, the Writer/Web component has a hard time even displaying HTML 3.2
correctly, so the help files breathe the spirit of 1985. The full text search does not work
correctly and never has.</p>

<h3><a name="ApplicationHelp-UIIssues"></a>UI Issues</h3>

<p>The content and structure of the help files do not show a clear distinction between
referential, conceptual and instructional information. On looking for guidance, users can
stumble over files that just list the UI elements of a dialog with one explanatory sentence
but with no indication of the context.</p>

<h3><a name="ApplicationHelp-MaintenanceIssues"></a>Maintenance Issues</h3>

<ul>
	<li>A rather complicated architecture (understatement!) in terms of maintenance. The
only found document describing what's going on in any detail can be found at: <a href="http://www.openoffice.org/documentation/online_help/OOo2HelpAuthoring.pdf"
class="external-link" rel="nofollow">Understanding and Authoring OpenOffice2.0Online Help</a>.
This is a cumbersome document which doesn't directly explain how to assign new ids to help
items, where to put them etc., given the hierarchical nature of the help system.</li>
</ul>


<ul>
	<li>New volunteers desiring to get involved with authoring or changing any help item
would likely need to install the "Help Authoring" extension, which can be found at: <a
href="http://people.apache.org/~jsc/test/helpauthoring.oxt" class="external-link" rel="nofollow">http://people.apache.org/~jsc/test/helpauthoring.oxt</a>.
Once this extension is installed, adding or changing help texts is a bit easier but followup
maintenance using Perl scripts found in the repository are needed for adding new help texts.</li>
</ul>


<ul>
	<li>Since current help system is stored <b>within</b> the source repository,
anyone needing to make changes must be a project committer. This seems rather burdensome to
new volunteers who would like to participate in this area.</li>
</ul>


<ul>
	<li>Because the Online Help is "homegrown" and difficult to fathom, it will always
need special attention. So, it is not very sustainable in its current form.</li>
</ul>



<h2><a name="ApplicationHelp-MovingForward"></a>Moving Forward </h2>

<p>Since we're off to a fresh start, this is what we ought to do with the help:<br/>
(see also the following mail thread: <a href="http://markmail.org/message/tl5lsy4cxaa3s6lx"
class="external-link" rel="nofollow">http://markmail.org/message/tl5lsy4cxaa3s6lx</a>)</p>


<h3><a name="ApplicationHelp-HelpFileSourceFormat"></a>Help File Source
Format</h3>

<ul>
	<li>move to a standard format: DITA, EPUB have been suggested</li>
	<li>highly desirable that new system is supported by a range of open source authoring
and validation tools</li>
	<li>highly desirable that the Help system be a stand alone entity apart from the source
build process &#8211; a separate svn tree<img class="emoticon" src="/confluence/images/icons/emoticons/help_16.gif"
height="16" width="16" align="absmiddle" alt="" border="0"/> with appropriate permissions
for that area alone</li>
	<li>create an easy authoring workflow to enable participation</li>
</ul>


<h3><a name="ApplicationHelp-HelpViewer"></a>Help Viewer</h3>

<ul>
	<li>use current technology (HTML 4+, CSS4, bells and whistles)</li>
	<li>don't let the user decide on which route to find info (TOC, index, search), give
a search input field and let the help find the best results</li>
	<li>fix the search engine</li>
	<li>integrate the help viewer with the UI</li>
</ul>


<h3><a name="ApplicationHelp-HelpContentandStructure"></a>Help Content and
Structure</h3>

<ul>
	<li>Limit help content to instructions, and some basic concepts</li>
	<li>Show reference information ("enter your name in this field") where it's needed,
on the UI, side-by-side to the element it refers to. For that, we need rich formatting in
"bubbles" (extended tips).</li>
	<li>Reduce the amount of offline help content and allow to expand to online sources</li>
	<li>Allow rich media in help files</li>
</ul>


<h3><a name="ApplicationHelp-MigrationtoaNew%2FDifferentSystemquestions%2Fchallenges"></a>Migration
to a New/Different System &#8211; questions/challenges</h3>

<ul>
	<li>Current Help source files (*.xhp) are xml defined by xmlhelp.dtd (/main/xmlhelp/util)<br/>
and utilize main_transform.xsl (same directory). How to migrate this content to a new system.<br/>
(some preliminary  testing has been done renaming *.xhp files to *.xml and using the stylesheet
to ascertain what this does exactly.)</li>
	<li>How would current indexes be generated?</li>
	<li>What application changes would need to made to accommodate this?</li>
</ul>


    </div>
        <div id="commentsSection" class="wiki-content pageSection">
        <div style="float: right;" class="grey">
                        <a href="https://cwiki.apache.org/confluence/users/removespacenotification.action?spaceKey=OOOUSERS">Stop
watching space</a>
            <span style="padding: 0px 5px;">|</span>
                <a href="https://cwiki.apache.org/confluence/users/editmyemailsettings.action">Change
email notification preferences</a>
</div>
        <a href="https://cwiki.apache.org/confluence/display/OOOUSERS/Application+Help">View
Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=27821669&revisedVersion=5&originalVersion=4">View
Changes</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message