RFC: Upgrading to DocBook 5.0

[Hiroki Sato]

Gabor Kovesdan <gabor at FreeBSD.org> wrote
  in <51AF556A.40803 at FreeBSD.org>:

ga> Em 05-06-2013 14:10, Hiroki Sato escreveu:
ga> > Gabor Kovesdan <gabor at FreeBSD.org> wrote
ga> >    in <519FA4FE.4030305 at FreeBSD.org>:
ga> >
ga> > ga> username --> systemitem class="username"
ga> > ga> groupname --> systemitem class="groupname"
ga> > ga> hostid role="fqdn" --> systemitem class="fqdomainname"
ga> > ga> hostid role="hostname" --> systemitem class="fqdomainname"
ga> > ga> hostid role="domainname" --> systemitem class="fqdomainname"
ga> > ga> hostid role="netmask" --> systemitem class="netmask"
ga> > ga> hostid role="mac" --> systemitem class="etheraddress"
ga> > ga> hostid role="ipaddr" --> systemitem class="ipaddress"
ga> > ga> hostid --> systemitem
ga> >
ga> >   Hmm, I do not like to create "a rule" to mark up both a username and
ga> >   a hostname by using <systemitem> element without attribute.  Even if
ga> >   the rendering results are the same, they are different.  Is it
ga> >   problem with allowing both writing <systemitem>s without attribute
ga> >   and adding attributes into them later (or at the same time)?  I do
ga> >   not think limiting the vocabulary is useful for learning.  Allowing
ga> >   people who are not familiar with DocBook to mark up by using
ga> >   <systemitem> only should be enough if it is really an issue.
ga> Technically it is easily possible to convert them "correctly", i.e. as
ga> described above, it was just my suggestion to leave out class
ga> attributes. It is also possible to allow systemitem with and without
ga> the class attribute specified.

 Yes, it is just my preference, too.

ga> > ga> This is actually a type of file and the filename class attribute
ga> > may
ga> > ga> also be devicefile, which expresses its semantics. Again, we
ga> > should
ga> > ga> consider dropping the class attributes to simplify things:
ga> > ga> devicename --> filename class="devicefile"
ga> > ga>
ga> > ga> These are not actually distinguished in formatting and the package
ga> > ga> element expresses them better:
ga> > ga> filename role="package" --> package
ga> > ga> filename role="port" --> package
ga> >
ga> >   package should support a role to distinguish if it is a port or a
ga> >   package because the linkend can be different.  The following DSSSL
ga> >   fragment was removed in our XSLT:
ga> >
ga> > ----
ga> >          (element filename
ga> >            (let* ((class         (attribute-string (normalize "role"))))
ga> >              (cond
ga> >               ((equal? class "package")
ga> >                (let* ((urlurl    "http://www.FreeBSD.org/cgi/url.cgi")
ga> >                       (href      (string-append urlurl "?ports/"
ga> >                                                 (data (current-node))
ga> >                                                 "/pkg-descr")))
ga> >                  (create-link (list (list "HREF" href)) ($mono-seq$))))
ga> >               (else ($mono-seq$)))))
ga> > ----
ga> It's true that I didn't notice this distinction in the rendering. But
ga> why not addding this link to both packages and ports? My personal
ga> impression is that there are people, who mostly use packages and
ga> others, who use ports. This preference is independent from the
ga> context. If the text talks about the textproc/docproj ports but I
ga> prefer dealing with packages, I will still want to install the package
ga> and vice versa. In the essence, they are the same. This is why I would
ga> not distinguish them.

 I think both can have a link, but ftp/wget and wget-1.14.tbz will
 have different linkends, for example.  Although a single linkend like
 http://.../ports/ftp/wget.html can be applied to the both via XSLT,
 algorithms of URL generation from the markup text become different
 between ports and packages.  Simplification of markup restricts such
 a possibility, I think.

-- Hiroki
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 196 bytes
Desc: not available
URL: <http://lists.freebsd.org/pipermail/freebsd-doc/attachments/20130609/0148efa6/attachment.sig>