Default Mallard <list> element translated incorrectly

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.

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

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.

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.

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.

> 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.

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.

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?

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

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

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

Thanks!

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