bug-texinfo
[Top][All Lists]
Advanced
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Small document and sample HTML and DocBook

From: Noah Slater
Subject: Small document and sample HTML and DocBook
Date: Wed, 24 Dec 2008 21:39:58 +0000
User-agent: Mutt/1.5.18 (2008-05-17) 
Hello,

After playing around some more, I would like to make a suggestion for the
texi2html output. This is based on my application use case of using Texinfo
documents to build web small pages from.

The design goal from my perspective is to make Texinfo editing as easy as many
of the other lightweight "plain text" markup languages. Obviously, Texinfo is
more powerful in spades, but if we can ease the necessary complexity I think it
would go a long way in improving the potential take-up of this format as an
option for the application I am doing.

Lets say a use of my application wanted to make a quick essay about how excited
they are to be in the holiday spirit, I would like it to be as simple as:

  \input texinfo
  @settitle Thoughts for the Day

  Today I am feeling happy because it is almost Christmas!

  @bye

The first thing that you might notice to be missing here is the @setfilename but
that is okay, because in my application the user is never responsible for
running makeinfo (or texi2html when it is widely available) so we can have the
software use the --output option correctly. This is no problem.

Having said that, it does puzzle me though that using --html correctly uses a
".html" extension, but using --docbook uses a ".info" extension. Seems like an
inconsistent bug/feature -- not sure which, heh.

We're also lacking an explicit node, which I think helps keep things simple.

At the moment, we get the following HTML:

  <html lang="en">
  <head>
  <title>Thoughts for the Day</title>
  <meta http-equiv="Content-Type" content="text/html">
  <meta name="description" content="Thoughts for the Day">
  <meta name="generator" content="makeinfo 4.11">
  <link title="Top" rel="top" href="#Top">
  <link href="http://www.gnu.org/software/texinfo/"; rel="generator-home" 
title="Texinfo Homepage">
  <meta http-equiv="Content-Style-Type" content="text/css">
  <style type="text/css"><!--
    ...
  --></style>
  </head>
  <body>
  Today I am feeling happy because it is almost Christmas!

  </body></html>

I would like to suggest that this be the output instead:

  <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" 
"http://www.w3.org/TR/html4/strict.dtd";>
  <html lang="en">
  <head>
    <title>Thoughts for the Day</title>
    <meta http-equiv="Content-Type" content="text/html">
    <meta name="generator" content="makeinfo 4.11">
    <link href="http://www.gnu.org/software/texinfo/"; rel="generator-home" 
title="Texinfo Homepage">
    <style type="text/css"><!--
      ...
    --></style>
  </head>
    <body>
      <h1>Thoughts for the Day</h1>
      <p>Today I am feeling happy because it is almost Christmas!</p>
    </body>
  </html>

The changes I have made are:

  * added a proper DOCTYPE, you might want to use "transitional" though

  * indented the output, but I wouldn't actually bother to do that in texi2html

  * dropped <meta http-equiv="Content-Style-Type" content="text/css"> as this is
    not needed in practice unless you are using something other than "text/css"

  * dropped <link title="Top" rel="top" href="#Top"> as this points to a
    non-existent anchor

  * added a <h1> element that contains the document title (important change)

  * made sure the paragraph is wrapped in a <p> element (important change)

At the moment, we get the following DocBook:

  <?xml version="1.0"?>
  <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"; [
    <!ENTITY tex "TeX">
    <!ENTITY latex "LaTeX">
  ]>
  <book id="book-root" lang="en">
    <title>Thoughts for the Day</title>
    <bookinfo>
      <abstract>
        <para>Today I am feeling happy because it is almost Christmas!</para>
      </abstract>
  </bookinfo></book><!-- Keep this comment at the end of the file
  Local variables:
  mode: sgml
  sgml-indent-step:1
  sgml-indent-data:nil
  End:
  -->

I would like to suggest that this be the output instead:

  <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd";>
  <article lang="en">
    <articleinfo>
      <title>Thoughts for the Day</title>
    </articleinfo>
    <simpara>Today I am feeling happy because it is almost Christmas!</simpara>
  </article>

The changes I have made are:

  * dropped the <?xml version="1.0"?> as this is not required, and adds nothing

  * replaced the DOCTYPE with a newer version, removing the entities

  * changed <book> to <article>

  * dropped id="book-root" from the root element

  * put the <title> into an <articleinfo> element

  * removed <bookinfo> and <abstract>

  * changed <para> to <simpara>

  * remove the final comment

I've covered some of this in my previous emails, but I thought I would take the
time out to bring it all together into a concrete suggestion.

Thanks for the ongoing help everyone, and merry Christmas!

-- 
Noah Slater, http://tumbolia.org/nslater
reply via email to
[Prev in Thread] Current Thread [Next in Thread]