Small document and sample HTML and DocBook
|
View:
New views
17 Messages
—
Rating Filter:
Alert me
|
 |
Small document and sample HTML and DocBook
by Noah Slater-4
::
Rate this Message:
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 |
|
|
Re: Small document and sample HTML and DocBook
by Karl Berry
::
Rate this Message:
\input texinfo
You may not even need the \input texinfo except to process with texi2dvi. (Clearly irrelevant for such a tiny file.) At least I'm pretty sure it's optional with makeinfo. 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. Ok, it's inconsistent, but the best solution is for you to specify the full filename anyway. We're also lacking an explicit node, which I think helps keep things simple. Until the documents become even a tiny bit more complicated, and the user wants to write sections. There is no escaping nodes then. But sure, for a single-topic file, it should work ok. I would like to suggest that this be the [HTML] output instead: ... * added a proper DOCTYPE, you might want to use "transitional" though The suggestion has been made before. We even generated a DOCTYPE at one time, as I recall. The experience was that having a DOCTYPE is nothing but a recipe for trouble with overzealous or buggy browsers, whereas omitting it has never hurt anything in practice. * indented the output, but I wouldn't actually bother to do that in texi2html Having more readable output wouldn't hurt ... * 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" Ok. * dropped <link title="Top" rel="top" href="#Top"> as this points to a non-existent anchor Ok. * added a <h1> element that contains the document title (important change) How the frontmatter gets handled in HTML has always been rather ad hoc. Using the @settitle string in the absence of actual node title seems reasonable. * made sure the paragraph is wrapped in a <p> element (important change) Yeah, the lack of a <p> is a bug. Regarding Docbook ... The changes I have made are: Are these changes something for Docbook output in general, or just for this type of nodeless document? (Obviously, the fewer special cases, the better.) Probably the Docbook output needs your thorough review, not just more ad hoc changes. * remove the final comment Ok, I guess that final comment in the docbook output is pretty bogus, looking at it. 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. Yes indeed. Thanks. Thanks for the ongoing help everyone, and merry Christmas! You too :). karl |
|
|
Re: Small document and sample HTML and DocBook
by Noah Slater-4
::
Rate this Message:
On Wed, Dec 24, 2008 at 06:28:26PM -0600, Karl Berry wrote:
> I would like to suggest that this be the [HTML] output instead: > ... > * added a proper DOCTYPE, you might want to use "transitional" though > > The suggestion has been made before. We even generated a DOCTYPE at one > time, as I recall. The experience was that having a DOCTYPE is nothing > but a recipe for trouble with overzealous or buggy browsers, whereas > omitting it has never hurt anything in practice. Unfortunately, this is not the case. :( Most browsers operate in two modes, standards mode and quirks mode. Standards mode is when the browser uses the most correct rendering model and applies CSS in the most correct way possible. Quirks mode is for older web pages and applies purposefully buggy rendering and CSS so as not to break things too badly. Designing modern CSS for a page that browsers render in quirks mode is insanely difficult, and so any CSS tutorial or expert will always tell you to make sure your documents are triggering standards mode first. These modes are triggered by DOCTYPEs, and a comprehensive list can be found: http://hsivonen.iki.fi/doctype/ (Activating Browser Modes with Doctype) The most commonly applicable DOCTYPE from that list is: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> This activates HTML 4.01 standards mode, and would be my *firm* recommendation. > * indented the output, but I wouldn't actually bother to do that in texi2html > > Having more readable output wouldn't hurt ... Sure, but pretty printing HTML is *really* hard. It's probably best to leave that to a tool like HTMLTidy if it becomes an issue. > * added a <h1> element that contains the document title (important change) > > How the frontmatter gets handled in HTML has always been rather ad hoc. > Using the @settitle string in the absence of actual node title seems > reasonable. Great! > Are these changes something for Docbook output in general, or just for > this type of nodeless document? (Obviously, the fewer special cases, > the better.) Probably the Docbook output needs your thorough review, > not just more ad hoc changes. My changes here were very general, and so should be broadly applicable. I am more than happy to help out with the DocBook output. -- Noah Slater, http://tumbolia.org/nslater |
|
|
Re: Small document and sample HTML and DocBook
by Patrice Dumas
::
Rate this Message:
On Tue, Jan 06, 2009 at 12:22:36PM +0000, Noah Slater wrote:
> > http://hsivonen.iki.fi/doctype/ (Activating Browser Modes with Doctype) > > The most commonly applicable DOCTYPE from that list is: > > <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> I found that it was hard to have valid html with the strict dtd, instead in texi2html Transitional is used: $DOCTYPE = '<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html401/loose.dtd">'; In texi2html had a plan to do an init file for strict xhtml (or maybe strict html) but never got around to do it. It would need much more css. That being said this would certainly be trivial to do on a coding point of view, but a css knowledge is needed. Also I would like to rework the css support in texi2html, to be more compatible with what makeinfo currently do, and to enhance (and fix) css, but after the merge. Currently info output is way higher on my list (and progressing rather neatly). > Sure, but pretty printing HTML is *really* hard. > > It's probably best to leave that to a tool like HTMLTidy if it becomes an issue. Agreed. I think that the texinfo to html software should keep output as much as possible like the .texi document was written, and let pretty printing to other tools. -- Pat |
|
|
Re: Small document and sample HTML and DocBook
by Noah Slater-4
::
Rate this Message:
On Tue, Jan 06, 2009 at 02:10:31PM +0100, Patrice Dumas wrote:
> On Tue, Jan 06, 2009 at 12:22:36PM +0000, Noah Slater wrote: > > > > http://hsivonen.iki.fi/doctype/ (Activating Browser Modes with Doctype) > > > > The most commonly applicable DOCTYPE from that list is: > > > > <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> > > I found that it was hard to have valid html with the strict dtd, instead > in texi2html Transitional is used: > $DOCTYPE = '<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html401/loose.dtd">'; > > In texi2html had a plan to do an init file for strict xhtml (or maybe > strict html) but never got around to do it. I think we should avoid XHTML because it causes more trouble than it's worth. If this is a controversial opinion on this list I am happy to spend some time digging out citations for you. (but I'd rather not, obviously) If it's not too hard, I would aim for full HTML strict output. If this is an insurmountable task, anyone who wants strict can use HTMLTidy. Whatever the case, I would choose one and stick with it. > It would need much more css. What would need more CSS? > That being said this would certainly be trivial to do on a coding point of > view, but a css knowledge is needed. I have been working on a default stylesheet for my GNU manual that balances æsthetics with readability and I would love to contribute this to texi2html and work with you on getting it broadly useful for distribution. My current draft is available at: http://periplum.org/dev/gnu/publish/trunk/doc/publish.html This is currently produced with: makeinfo --enable-encoding --html --no-split --css-ref=style.css I am also working on similar CSS for my O'Reilly book: http://books.couchdb.org/relax/ Is this something that interests you? > Also I would like to rework the css support in texi2html, to be more > compatible with what makeinfo currently do, and to enhance (and fix) css, but > after the merge. Currently info output is way higher on my list (and > progressing rather neatly). Not sure what this means. How can I help out? -- Noah Slater, http://tumbolia.org/nslater |
|
|
Re: Small document and sample HTML and DocBook
by Patrice Dumas
::
Rate this Message:
On Tue, Jan 06, 2009 at 01:25:38PM +0000, Noah Slater wrote:
> > I think we should avoid XHTML because it causes more trouble than it's worth. If > this is a controversial opinion on this list I am happy to spend some time > digging out citations for you. (but I'd rather not, obviously) texi2html is more controversy-proof than makeinfo since it is easy to customize the output. In the past I did an init file for texi2html (which would require updating), that turned the output into valid transitional xhtml. But I don't think that anybody ever asked, I think that I did that on my own. The aim was not to have a html compatible xhtml, but to have valid xhtml on its own. > If it's not too hard, I would aim for full HTML strict output. If this is an > insurmountable task, anyone who wants strict can use HTMLTidy. Whatever the > case, I would choose one and stick with it. > > > It would need much more css. > > What would need more CSS? strict HTML doesn't have <u> or <font>, not width in table... I attach the result of the use of http://validator.w3.org/ with a strict dtd, and the original file produced by texi2html. With Transitional, it is valid. > I have been working on a default stylesheet for my GNU manual that balances > æsthetics with readability and I would love to contribute this to texi2html and > work with you on getting it broadly useful for distribution. I am not that much interested in the stylesheets themselves, but rather in having appropriate class attributes in the output to let anybody do its own stylesheet. That being said shipping .css files to show examples of use would be nice, even more if the output is nice ;-) > My current draft is available at: > > http://periplum.org/dev/gnu/publish/trunk/doc/publish.html Indeed it looks good. > This is currently produced with: > > makeinfo --enable-encoding --html --no-split --css-ref=style.css I could use it to check that texi2html output is compatible with makeinfo --html output css-wise. > > Also I would like to rework the css support in texi2html, to be more > > compatible with what makeinfo currently do, and to enhance (and fix) css, but > > after the merge. Currently info output is way higher on my list (and > > progressing rather neatly). > > Not sure what this means. How can I help out? Myabe this is not the answer you are looking for but, as you already know, the idea is to replace C makeinfo with texi2html. For that texi2html has to converge to makeinfo to be strictly compatible. This, in turn, implies: * generating info with texi2html. This is my priority right now, and after some delay, I am devoting all my free software time slots to that task, and it is progressing well. * having texi2html converge toward makeinfo regarding the command behaviour. This should not be a big deal: + command line switches and processing are almost the same, only little change is needed + error messages and lines in error messages formatting have to be synced + minor other issues * convergence in html output. + As a first step texi2html output should take what is clearly superior in makeinfo --html output. + Also remove unneeded inconsistencies, for example in CSS classes. + and last decide the default html output when invoked as makeinfo --html, including missing css classes, progress toward strict html... such that the html output is at least as good as makeinfo --html output * using a gettext-like handling of internationalization -- Pat |
|
|
Re: Small document and sample HTML and DocBook
by Noah Slater-4
::
Rate this Message:
On Tue, Jan 06, 2009 at 03:52:37PM +0100, Patrice Dumas wrote:
> strict HTML doesn't have <u> or <font>, not width in table... > > I attach the result of the use of http://validator.w3.org/ > with a strict dtd, and the original file produced by texi2html. > With Transitional, it is valid. Ah, that makes sense. In the long run, moving to strict is probably good though. > > I have been working on a default stylesheet for my GNU manual that balances > > æsthetics with readability and I would love to contribute this to texi2html and > > work with you on getting it broadly useful for distribution. > > I am not that much interested in the stylesheets themselves, but > rather in having appropriate class attributes in the output to let > anybody do its own stylesheet. Of course, very important. > That being said shipping .css files to show examples of use would be nice, > even more if the output is nice ;-) Great, I would love to help design the default CSS for texi2html. > > Not sure what this means. How can I help out? > > Myabe this is not the answer you are looking for but, as you already > know, the idea is to replace C makeinfo with texi2html. For that texi2html > has to converge to makeinfo to be strictly compatible. This, in turn, > implies: Ah, yes... this all sounds good -- but is too much for me to really get involved with while I am making the push for my own GNU Project. However, I would love to be involved in the latter stages of finalising the CSS class name hooks and default stylesheets. Where would the DocBook work sit on that timeline? -- Noah Slater, http://tumbolia.org/nslater |
|
|
Re: Small document and sample HTML and DocBook
by Patrice Dumas
::
Rate this Message:
On Tue, Jan 06, 2009 at 03:03:01PM +0000, Noah Slater wrote:
> > Ah, yes... this all sounds good -- but is too much for me to really get involved > with while I am making the push for my own GNU Project. However, I would love to > be involved in the latter stages of finalising the CSS class name hooks and > default stylesheets. > > Where would the DocBook work sit on that timeline? Better wait after the merge -- at least if I am to do the work ;-). Currently the docbook output of texi2html should be bug-wise compatible with makeinfo --docbook output (this was in order to do systematic comparisons). There are already some FIXME in the docbook.init file (some for obvious makeinfo --docbook output bugs) and some docbook related items in the texi2html TODO list. Adding more in the TODO is something I can do at any time, though ;-). -- Pat |
|
|
|
|
|
Re: Small document and sample HTML and DocBook
by Noah Slater-4
::
Rate this Message:
On Tue, Jan 06, 2009 at 04:07:42PM +0100, Patrice Dumas wrote:
> On Tue, Jan 06, 2009 at 03:03:01PM +0000, Noah Slater wrote: > > > > Ah, yes... this all sounds good -- but is too much for me to really get involved > > with while I am making the push for my own GNU Project. However, I would love to > > be involved in the latter stages of finalising the CSS class name hooks and > > default stylesheets. > > > > Where would the DocBook work sit on that timeline? > > Better wait after the merge -- at least if I am to do the work ;-). > Currently the docbook output of texi2html should be bug-wise compatible > with makeinfo --docbook output (this was in order to do systematic > comparisons). There are already some FIXME in the docbook.init file > (some for obvious makeinfo --docbook output bugs) and some docbook > related items in the texi2html TODO list. Okay sure, this makes sense. I'm not working on the Texinfo to DocBook stuff at the moment, so there's no rush. -- Noah Slater, http://tumbolia.org/nslater |
|
|
Re: Small document and sample HTML and DocBook
by Patrice Dumas
::
Rate this Message:
On Tue, Jan 06, 2009 at 03:11:36PM +0000, Noah Slater wrote:
> On Tue, Jan 06, 2009 at 03:59:16PM +0100, Patrice Dumas wrote: > > 1. Error Line 692, Column 24: there is no attribute "BGCOLOR". > > > > <body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" > > It's probably best to drop all the colour attributes here and put it in CSS. Indeed... That's why I said some css stuff is needed ;-). > Similarly, the @lang attribute should really be on the <html> element. Right. > > 6. Error Line 694, Column 13: document type does not allow element "A" > > here; missing one of "P", "H1", "H2", "H3", "H4", "H5", "H6", "PRE", > > "DIV", "ADDRESS" start-tag. > > > > <a name="Top"></a> > > Probably best to wrap these inside <p> elements. I'd better avoid that. Empty <p> sometime leads to extraneous blank lines. Maybe in <div>? > > 11. Error Line 993, Column 21: there is no attribute "WIDTH". > > > > <thead><tr><th width="600%">mu–ltitable headitem</th><th width="700%">anot > > Is the @width specified in the Texinfo or could it be moved to CSS? It is in the Texinfo. A hack could be to dynamically generate the needed css and add it to the css output together with the html. > > 13. Error Line 1029, Column 6: element "U" undefined. > > > > <dt><u>c--ategory:</u> <b>d--effn_name</b><i> a--rguments...</i></dt> > > Probably best to use <em> and <strong> with class name hooks. Certainly. -- Pat |
|
|
Re: Small document and sample HTML and DocBook
by Noah Slater-4
::
Rate this Message:
On Tue, Jan 06, 2009 at 04:16:53PM +0100, Patrice Dumas wrote:
> I'd better avoid that. Empty <p> sometime leads to extraneous blank > lines. Maybe in <div>? Would make sense. -- Noah Slater, http://tumbolia.org/nslater |
|
|
Re: Small document and sample HTML and DocBook
by Karl Berry
::
Rate this Message:
triggering standards mode first.
Which have their own quirks and bugs and stupid design flaws. I do not find the standards are any kind of panacea. However, it's been some years since I tried <doctype>, since the last time I did, it was disaster. So I don't argue against trying it again. When we are moved to texi2html, I expect we can easily have several output modes, one with the 4.01/transitional doctype, one without, etc. Then people can try and we can gather some actual experience. |
|
|
Re: Small document and sample HTML and DocBook
by Noah Slater-4
::
Rate this Message:
On Mon, Jan 12, 2009 at 07:41:45PM -0600, Karl Berry wrote:
> triggering standards mode first. > > Which have their own quirks and bugs and stupid design flaws. I do not > find the standards are any kind of panacea. I never claimed it was a panacea. Of course, browsers will always have bugs, but triggering quirks mode is a massive problem for anyone trying to do sensible stylesheets. You don't want go there, it's simply too much effort. -- Noah Slater, http://tumbolia.org/nslater |
|
|
Re: Small document and sample HTML and DocBook
by Patrice Dumas
::
Rate this Message:
On Tue, Jan 06, 2009 at 01:25:38PM +0000, Noah Slater wrote:
> > http://periplum.org/dev/gnu/publish/trunk/doc/publish.html > > This is currently produced with: > > makeinfo --enable-encoding --html --no-split --css-ref=style.css The page doesn't seems to exist anymore. Is it available somewhere? -- Pat |
|
|
Re: Small document and sample HTML and DocBook
by Noah Slater-4
::
Rate this Message:
On Tue, Sep 08, 2009 at 10:39:29PM +0200, Patrice Dumas wrote:
> On Tue, Jan 06, 2009 at 01:25:38PM +0000, Noah Slater wrote: > > > > http://periplum.org/dev/gnu/publish/trunk/doc/publish.html > > > > This is currently produced with: > > > > makeinfo --enable-encoding --html --no-split --css-ref=style.css > > The page doesn't seems to exist anymore. Is it available somewhere? Nope, but Alfred M. Szmidt started doing something similar: http://planet.gnu.org/~ams/ Hope that helps, -- Noah Slater, http://tumbolia.org/nslater |
|
|
Re: Small document and sample HTML and DocBook
by Patrice Dumas
::
Rate this Message:
On Tue, Sep 08, 2009 at 10:23:10PM +0100, Noah Slater wrote:
> > Nope, but Alfred M. Szmidt started doing something similar: > > http://planet.gnu.org/~ams/ > > Hope that helps, Thanks! -- Pat |
| Free embeddable forum powered by Nabble | Forum Help |
