Difference between revisions of "Help Standardisation issues"

Revision as of 10:54, 7 January 2007

The conversion of the entire help system to the new xml specification was a huge and doubtless heroic task. In the process a number of convenience measures had to be taken, with the result that in some cases the new specification is not fully obeyed.

This is a page to record variations and discuss solutions.

Simplified background notes

Help sources are written in xhp, which is an xml format specifically for OOo Help. The xhp files are processed by main_transform.xsl to produce html, which is in essence displayed by the OOo Help Viewer (although in practice it is more complicated than this). The Help system is very well defined in OOo2HelpAuthoring.pdf "Understanding, authoring and editing OpenOffice.org Help".

The variation of help sources from specification becomes more important as help authoring is opened up for user contributions - it is another 'entry barrier'.

A major consideration in changing help sources to bring them into specification is that any change may trigger a request for translation into other languages - which might cause much unnecessary work.

Issues

These are simply listed for the main part. Proposed solutions to come.

• Paragraphs within tables
  • Currently main_transform.xsl changes any paragraph role inside a table by adding "intable" to it. The original reason was probably to do with layout. Thus the system does not deliver the paragraph role specified by the help author.

• Heading linked to itself
  • Heading which are linked to themselves are intercepted by main_transform.xsl to remove the link. This doesn't conform to the xhp spec - and is confusing to read in the help sources.

• Embedded variables
  • The <embed> element should embed only sections and paragraphs according to the specification. However main_transform.xsl also allows it to embed variables, enclosed in <p class="embedded"> </p> tags.

• How-to-get
  • Help sources that refer to '/00/00000004.xhp#wie' are intercepted by main_transform.xsl, to provide a specially formatted section which starts (in English) "To access this command..."
  • solution: main_transform.xsl appears to implement an alternative method using sections, although it may be unused at present. There are 462 instances of the old unconforming references, so a script might be the only practical way to solve this.

• Demoted embedded headings
  • Any level 1 heading is demoted to level 2 on embed, which is contrary to the xhp spec.
  • working towards a solution: This may only happen when embedding a single heading paragraph, in which case it could be solved if embed allowed a text_only mode. A Perl script could discover the extent of this. Would solving this one issue allow main_transform.xsl to be (considerably) simplified with the removal of 'mode="embedded"'?

• Table classes
  • main_transform.xsl intercepts single cell tables and forces them to be class="onecell"; it also intercepts tables where the first cell is an image and forces them to be class="icontable". Thus the author has lost control (eg can't make an image table with a border).
  • Possible solution: table class could be specified in xhp - eg <table class="onecell" .. >. As happens already with <table class="wide" .. >. This would hopefully not trigger re-translation.

• html tags
  • main_transform.xsl outputs html tags containing attributes that might be better set in the stylesheet. eg the default table style <table border="1" class="border" cellpadding="0" cellspacing="0" >. This may well be because the Help Viewer does not fully implement stylesheets.
  • Solution: await improved Help Viewer?

• Stylesheets
  • default.css does not define some classes outputted by main_transform.xsl: .paragraph, .paragraphintable, .embedded, .border, .icontable, .onecell. Also <ol> and <ul> have no style attached. This works OK in the OOo HelpViewer, but when viewing the html with a browser the default style looks wrong.
  • Solution: define as necessary. Not that important, and possibly the Help Viewer cannot handle some of these styles yet anyway.

• Redundant attributes
  • The paragraph element has two attributes that were used in the changeover from the old Help system. Is there any reason they are still needed?

• 'createlink' template in main_transform.xsl
  • tests for # to identify an internal link, but an external link might be http://.......#anchor - is this a potential bug?
  • possible solution: test for not starting with "http://" as well as "#"