From: xah lee <xah@xahlee.org>
To: emacs-pretest-bug@gnu.org
Subject: texinfo generates invalid html
Date: Sat, 17 May 2008 08:49:04 -0700 [thread overview]
Message-ID: <21886EF4-051C-4307-9601-9D002D90280E@xahlee.org> (raw)
The elisp document generated by texinfo in html is not valid html.
Here's the major problems:
-------------------------------------
Problems with texinfo generated html, with respect to html 4
transitional:
* there's no doctype declaration.
* when there's a footnote, it is generated as <p><hr></div>
which is invalid.
-------------------------------------
Problems with respect to html4 strict:
* “<ol type=1 start=1>” should just be “<ol>”.
* sometimes there's “</p></blockquote>” but missing a
opening “<p>”.
* whenever there's a “<b>Common Lisp note:</b>”, it should
have a “<p>” wrapped around the block, since it's inside
“<blockquote>” and html4strict requires it.
-------------------------------------
Other minor problems:
* the css is plastered into every page. It should be one css
file instead.
* it should declare utf8 as the charset. (so that it doesn't
need to do a lot html character encoding)
* the ending </p> is often not used.
-------------------------------------
Dead Links to external docs
In the elisp manual (one node per html page, roughly 850 html pages),
there are 70 (local) links to other GNU documents. The local links
are nice in that they provide cross-reference, but if one hosts only
the elisp doc, all these local links will be dead.
Therefore, it would be nice, to have perhaps at texinfo level to
embed markers to links that cross-ref to external docs, or perhaps at
the html conversion level to provide a option to filter local links,
so that local links can replaced as non-links (such as “See Emacs
manual node on Abbrev”) or full http links to the right uri at
gnu.org.
-------------------------------------
Use of ascii...
texinfo still use the convention of backtick ` and straight single
quote ' to emulate curly ones “” and ‘’, and other ascii
kludge such as “=>” instead of “⇒”. The ability to
displaying these chars has been widely available on commercial
platforms since mid 1990s, and on linuxes since about 2003 or so
(emacs itself support unicode to a practical degree since emacs 21,
released in 2001). It is perhaps time to update gnu doc convention to
utf8 and use the proper characters.
-------------------------------------
Note:
The HTML generated by texinfo is actually far superior than other
org's, such as those of perl, pyhton, java, in the sense that when
sending the html to w3c's validator, texinfo's html actually contain
just a few errors, all are fixable. While other org's such as python
(which was generated from TeX), are so messy that is not fixable.
Kudos to the textinfo developer(s).
PS I had problem with the quality of FSF's documentation uri. Namely,
sometimes the doc's uri disappears, so that people cannot reliably
link to it. Also, some links in the doc are dead links to to the
transformation scheme of links from texinfo to uri. For detail, see:
http://xahlee.org/emacs/gnu_doc.html (warning: rant)
Xah
xah@xahlee.org
∑ http://xahlee.org/
☄
next reply other threads:[~2008-05-17 15:49 UTC|newest]
Thread overview: 2+ messages / expand[flat|nested] mbox.gz Atom feed top
2008-05-17 15:49 xah lee [this message]
2008-05-17 16:41 ` texinfo generates invalid html Eli Zaretskii
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=21886EF4-051C-4307-9601-9D002D90280E@xahlee.org \
--to=xah@xahlee.org \
--cc=emacs-pretest-bug@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.