Default Mallard <list> element translated incorrectly

Bug #1649554 reported by Chris Perry
6
This bug affects 1 person
Affects Status Importance Assigned to Milestone
ubuntu-docs (Ubuntu)
Fix Released
Medium
Gunnar Hjalmarsson

Bug Description

When "type" is not specified in a Mallard <list> element the Mallard spec says it should display as a bulleted (unordered) list. This is true when the .page file is displayed using yelp but not when the .page file is translated into HTML (where you get a numbered list). This is a bug. The HTML should be displayed as specified by the Mallard spec.

Here's an example <list> element without "type" specified.

<list>
  <item><p><code>GTK_MESSAGE_INFO</code></p></item>
  <item><p><code>GTK_MESSAGE_WARNING</code></p></item>
  <item><p><code>GTK_MESSAGE_QUESTION</code></p></item>
  <item><p><code>GTK_MESSAGE_ERROR</code></p></item>
  <item><p><code>GTK_MESSAGE_OTHER</code></p></item>
</list>

Here's the link to the relevant page of the Mallard spec:

http://projectmallard.org/1.0/mal_block_list

Revision history for this message
Gunnar Hjalmarsson (gunnarhj) wrote :

I found the culprit and committed a change. However, I think we need to build the HTML and watch out for possible undesired side effects before we can consider this bug really fixed.

Changed in ubuntu-docs (Ubuntu):
assignee: nobody → Gunnar Hjalmarsson (gunnarhj)
importance: Undecided → Medium
status: New → Fix Committed
Revision history for this message
Doug Smythies (dsmythies) wrote :

I've subscribed Matthew East, in case he has any historical information.

Revision history for this message
Chris Perry (clissold345) wrote :

I did a bzr pull to get Gunnar's fix and did a test by temporarily changing my local copy of mouse-mousekeys.page. Yes the fix seems to work. If type isn't specified in the <list> element, you get bullets in the html. It looks like the "disc" bullets. So:

<list>
  <item><p>First</p></item>
  <item><p>Second</p></item>
  <item><p>Third</p></item>
</list>

gives you:

<list type="disc">
  <item><p>First</p></item>
  <item><p>Second</p></item>
  <item><p>Third</p></item>
</list>

I haven't noticed any (glaring) undesired side effects so far.

Revision history for this message
Chris Perry (clissold345) wrote :

On reflection I think it's best if writers say what kind of <list> they want. Eg if they want bullets, it's best if they say so, rather than relying on defaults. And it's (slightly) clearer if another writer comes along in a year or two and wants to change the text.

Revision history for this message
Chris Perry (clissold345) wrote :

The fix does seem to have exposed some problems. Eg the procedure "Check with Disk Usage Analyzer" on disk-capacity.page was wrongly marked up as a <list> and it's now lost its numbering, which is incorrect. I'll investigate some more and report back in a day or two. The command grep "<list" *.page seems useful in finding pages that may have problems.

Revision history for this message
Doug Smythies (dsmythies) wrote :

> On reflection I think it's best if writers say what kind of <list> they want.

Agreed.

> The command grep "<list" *.page seems useful in finding pages that may have problems.

Yes, all other uses should be checked.

I also started looking back through the doc team mail archives for related discussions, but only got to 2004 before giving up due to a high number of html e-mails that often trigger the "list" search.

@Chris: Note that it might not always be a bug if the html display differs from the Mallard specification. The whole purpose of the ubuntu.xsl file is to provide overrides to the defaults, in addition to adding some functionality.

Revision history for this message
Gunnar Hjalmarsson (gunnarhj) wrote :

On 2016-12-14 14:18, Chris Perry wrote:
> The fix does seem to have exposed some problems. Eg the procedure
> "Check with Disk Usage Analyzer" on disk-capacity.page was wrongly
> marked up as a <list> and it's now lost its numbering, which is
> incorrect.

Please note that this is another example of previous inconsistency. It has been bullets when using yelp for a long time. (But I agree that numbers is better in a step-by-step list.)

On 2016-12-14 17:15, Doug Smythies wrote:
> @Chris: Note that it might not always be a bug if the html display
> differs from the Mallard specification. The whole purpose of the
> ubuntu.xsl file is to provide overrides to the defaults, in addition
> to adding some functionality.

While that is true, I suppose it has never been the intention to use different list style types in the HTML version compared to the yelp version.

Revision history for this message
Chris Perry (clissold345) wrote :

About 60 pages in the desktop help use <list> elements. (I listed them using the command grep "<list" *.page.) Can I go through them and (where possible) tidy up the help by putting in type="disc" (that's the bullet style that we are using)? I was planning to do the changes manually - not of course via a global replace - each time checking the html (but not checking the page appearance using yelp).

Most of the uses of <list> seem straightforward. However, there's a handful of unusual/complicated uses, which I may well leave alone. (If in doubt, leave it alone.)

So far I've noticed three short procedures that have been wrongly marked up using <list>, so I'm planning to change those too. They'll be changed to <steps> elements.

I'll just be changing markup (not the English text) so there is (surely) no impact on the translators. This is basically a simple job (though there are 60 pages to check). Can anything go wrong?

Revision history for this message
Gunnar Hjalmarsson (gunnarhj) wrote :

While I only would have changed the lists which have been unintentionally wrong, being specific is never wrong. Please go ahead.

Revision history for this message
Chris Perry (clissold345) wrote :

Thanks. I'll check and change the pages in batches (probably one or two batches a day).

Revision history for this message
Chris Perry (clissold345) wrote :

I've now finished revising the <list> elements.

Revision history for this message
Gunnar Hjalmarsson (gunnarhj) wrote :

Thanks!

Revision history for this message
Launchpad Janitor (janitor) wrote :

This bug was fixed in the package ubuntu-docs - 17.04.1

---------------
ubuntu-docs (17.04.1) zesty; urgency=medium

  * scripts/validate.sh:
    - Modified so it can be called via a symlink from 'ubuntu-help/C'
      or 'html'.
  * power-hibernate.page:
    - Changed command due to upstart->systemd transition.
  * Bump version to 17.04 / zesty.
  * html/ubuntu.xsl:
    - Make unordered lists bulleted and not numbered (LP: #1649554).
  * keyboard-layouts.page:
    - Note about how to show rarely used xkb layout variants.
  * Updated ubuntu-help.pot.
  * debian/compat, debian/control:
    - Bump to debhelper version 9

  [ Chris Perry ]
  * tips-specialchars.page:
    - Section "Compose key" updated (LP: #1624778).
  * addremove-ppa.page:
    - Revise PPA description (LP: #1628706).
  * keyboard-layouts.page:
    - Move text of marginal note.
  * mouse-middleclick.page, mouse-touchpad-click.page:
    - Revise description of middle-click from touchpad (LP: #1617718).
  * power-lowpower.page:
    - Update since related control in "System Settings -> Power" has
      been removed (LP: #1599264, LP: #1641786).
  * accounts-add.page, net-firewall-on-off.page:
    - Minor clarifications.
  * net-wireless-*.page, net-problem.page:
    - GUI conformity modifications (LP: #1637126)
    - New shared section (LP: #977251)
  * addremove-install.page, addremove-remove.page:
    - Clearer description of Ubuntu Software's focus on applications
      (LP: #1637861).
    - Mentioning of snaps (LP: #1658785).
  * printing-setup.page:
    - Section about network printer added (LP: #1630272).
  * mouse-mousekeys.page:
    - Improved description of mouse keys (LP: #964727).
  * disk-*.page:
    - GUI conformity modifications (LP: #1651360).
  * List type explicitly stated on multiple pages.
  * addremove-creator.page:
    - New page describing Startup Disk Creator (LP: #1569532).
  * security-settings.page:
    - New page describing the Security & Privacy panel in System
      Settings (LP: #1200381).

  [ Doug Smythies ]
  * scripts/validate.sh:
    - Changed to --strict validation.
  * ubuntu-help/C/legal.xml:
    - Specify https to avoid a "permanently moved" redirection.

 -- Gunnar Hjalmarsson <email address hidden> Mon, 20 Feb 2017 15:11:00 +0100

Changed in ubuntu-docs (Ubuntu):
status: Fix Committed → Fix Released
To post a comment you must log in.
This report contains Public information  
Everyone can see this information.

Other bug subscribers