[libvirt] [PATCH] docs: Make anchors follow HTML5

[Daniel P. Berrangé]

On Wed, Aug 28, 2019 at 10:48:59AM +0100, Daniel P. Berrangé wrote:
> On Wed, Aug 28, 2019 at 10:18:45AM +0200, Michal Privoznik wrote:
> > According to HTML specification, <a name=''> works in HTML4, but
> > <a id=''> works in both HTML4 and HTML5. This is followed even in
> > docs/page.xsl where HTML bookmark links are generated only for
> > those anchors which have @id attribute.
> 
> I'm pretty sure we had tried 'id' in our docs a long time ago
> and hit some problem, but I've not yet found record of what
> it was....

Seems I was remembering the wrong way around :-)

  commit 4e42ff6b7e1b5dc2911075a3eb7b86cd2075cfd3
  Author: Daniel P. Berrange <berrange at redhat.com>
  Date:   Wed Jul 26 15:52:42 2017 +0100

    docs: switch to using 'id' attribute instead of 'name' for links
    
    The 'name' attribute on <a...> elements is deprecated in favour
    of the 'id' attribute which is allowed on any element. HTML5
    drops 'name' support entirely.
    
    Signed-off-by: Daniel P. Berrange <berrange at redhat.com>

and we're obviously not doing a very good job at avoiding
use of 'name' since then, as we've also had


  commit d89fa8306e97492d3c54875a3665a5fd4d310010
  Author: Andrea Bolognani <abologna at redhat.com>
  Date:   Wed Aug 23 13:55:01 2017 +0200

    docs: Define anchors correctly in pci-hotplug
    
    HTML5 obsoletes the 'name' attribute in favor of 'id',
    and our TOC generator apparently follows the recommendation
    to the letter, resulting in a broken TOC if you use the
    old-school attribute.
    
    Signed-off-by: Andrea Bolognani <abologna at redhat.com>


commit 5726e4723473d047977db414b027de6e3d19bed8
Author: Peter Krempa <pkrempa at redhat.com>
Date:   Thu Aug 15 10:14:08 2019 +0200

    docs: Make anchors in API html files clickable/linkable
    
    Use 'id' instead of 'name' for anchors which adds the hidden clickable
    headerlink helper so it's way simpler to link to a specific part of the
    docs.
    
    Signed-off-by: Peter Krempa <pkrempa at redhat.com>
    Reviewed-by: Ján Tomko <jtomko at redhat.com>


So perhaps we need a syntax-check  rule added to blacklist name=
in the docs directory.

In any case

 Reviewed-by: Daniel P. Berrangé <berrange at redhat.com>


Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|