Help talk:Using Templates and HTML in Note Fields

Pass 1

Copied from ISFDB:Community Portal/Archive/Archive24#New Help page on HTML use -DES ^Talk 14:25, 22 July 2012 (UTC)b

I have just created Help:Using HTML in Note Fields, as I recall that this subject confused many editors, both in how to enter HTML and how to understand HTML that had been entered by others. It is not yet linked from any other help page. Please take a look and let me know your views, and whether you think this is acceptable to link to from appropriate parts of the help system. -DES ^Talk 02:23, 5 December 2011 (UTC)

Looks good, though I'm not sure that it's correct to say that <br> "is considered poor style" in a guide to writing HTML. Just because <br /> is required in XHTML, that doesn't mean <br> isn't proper HTML. Or maybe things have changed since I learned HTML. Will HTML5 require a slash to close single tags (like <p> and <hr>), not just the paired tags? (I think XHTML requires everything to be closed.) Mhhutchins 03:31, 5 December 2011 (UTC)

XHTML does require everything to be closed, and won't accept <br> or similar formations, as I understand it. Current texts on HTML discourage the <br> form. However, I just looked through the HTML5 docs in some detail, and found that it considers <br> to be normal. I will change the text. -DES ^Talk 04:42, 5 December 2011 (UTC)

BTW HTML5 is treating <p> as a paired tag, with the end of the paragraph to be marked with </p>. It is removing many "purely presentational" elements and attributes that were previously deprecated in favor of CSS3, such as the font tag. -DES ^Talk 06:59, 5 December 2011 (UTC)

Looks useful, but I'm a little concerned about what it might encourage. It's possible to totally break a submission with invalid HTML/XML that means it can't be fixed without really special knowledge on the part of a moderator. (No, I'm not going to explain how to submit such.) I agree with Michael that "is considered poor style" probably isn't that helpful at the moment. But if the "Links" section can be left till later, I'm fairly OK with it. But it's 4AM here and I may not be talking sense. (I seem to be speaking up for European Mods and Editors that DO go to sleep at natural hours, to talk to North American Editors that find this time quite OK.) BLongley 04:03, 5 December 2011 (UTC)

Since people DO use these, and they are present in many existing records, new editors will see them. This means that a) thy will want to know what they mean and do, and b) existing examples will be imitated. Therfore I thought it better to provide a very limited list of acceptable HTML to show people what forms are acceptable, and how to do them correctly. I thought it would also serve as a reference for moderators on what HTML constructs are safe, with the idea that anything not in this list would be at least queried by a mod when approving. It would be nice to have the software itself warn of possibly invalid html when a submisison is presented for approval -- maybe someday. -DES ^Talk 04:42, 5 December 2011 (UTC)

I like the page; I think it finds a good balance between completeness and simplicity. I would offer a few suggestions: (1) I think you could improve that balance a bit by not mentioning the nested <ul> commands; I think that's used rarely enough that it's not necessary; (2) You write as if the use of <li> without a matching </li> is going to fail at some point. The HTML 4 Standard recommends using that format. There are so many web pages written in HTML 4 that I cannot imagine any situation under which browsers will not be able to properly interpret a strict 4.0 page. (3) Others have raised concerns about your wording on <br> vs. <br />. I think the current wording is still misleading. In particular, you write "However future versions of HTML are expected to support the <br> form", which sounds as if earlier versions did not support the <br> tag. Yet that has been the recommended tag from HTML 1.0 through 4.0 (yes, I did build web pages in HTML 1.0). And I think that the wording that "some editors consider <br> to be poor style" almost certainly exaggerates the number of such editors (it would be like saying "some Geologists believe in the young Earth theory"). (4) Under the section on "Links", it might be worth noting that editors should only add links to pages that won't change; and possibly mention that links to Locus1 are not permanent links, and hence shouldn't be used.

Regardless of my list of issues, I think this is quite a useful help page. Chavey 08:16, 5 December 2011 (UTC)

I like it. I think if you mentioned in the intro section (or make it have two sub-sections, one for "paired tags" and one for) "unpaired tags", and then described that they can be unclosed or self-closed and gave an example, that might help. It keeps the opening/closing concept all in one spot. Then when you get to BR you can call it an unpaired tag and mention they might see it one of two ways, with no further explanation. --MartyD 11:27, 5 December 2011 (UTC)

(unindent) Thank you for your comments. Earlier this year, I took an HTML & CSS course where both professor and text strongly encouraged writing all HTML so that it was also XHTML compliant, and I got the impression that this was likely to be required in future versions. But on reading through the HTML5 current draft, I find that it explicitly preserves the distinction between HTML and XHTML syntax checking, and explicitly says that rendering agents arexpected to ignore minor syntax errors in HTML mode, and also explicitly permits the <li> tag's closing tag to be omitted even in strict XHTML mode, IF the next element is another <li> tag or the end of the document. (This seems to mean that if the list is properly closed, the very last li element must be closed or an error will occur in strict XHTML mode. But that is a subtlety not relevant to HTML documents, it seems.)

On nested lists, the reason that I mentioned them is that I know that they have been used in the ISFDB, in fact I think i may have created one or two myself, and I know I have edited notes where another editor had created them. I wanted to document forms that editors might see in valid note entries. Do you think, in light of that, that I should omit them from the page?

I will rewrite the page simplifying further, not privilaging XHTML syntax, and incorporating other suggestions above. -DES ^Talk 16:27, 5 December 2011 (UTC)

Pass 2

Copied from ISFDB:Community Portal/Archive/Archive24#New Help page on HTML use -DES ^Talk 14:25, 22 July 2012 (UTC)b

Rewrite done, opinions sought. -DES ^Talk 17:54, 5 December 2011 (UTC)

Very nice! Some comments: (i) I made 3 minor changes to the "Links" section (see the history for the details). (ii) There's a little bit of redundancy between the section on "Unpaired Tags" and the following section on "Line Breaks", you might want to re-read those together and see if that can be improved a bit; (iii) You have a section on "Unnumbered Lists", for the <ul> tag. The HTML 4.0 Standard says the name of that tag is "Unordered Lists" (emphasis mine), which is the only way to make sense of the name "Ordered List" for the <ol> tag. (iv) You asked about whether you should leave in the nested Unordered lists. I have mixed feelings about it, but I guess that I wouldn't mind leaving it in, but would prefer if you left it for the end of that section, e.g. after the "Example". (Always do the standard stuff first, the special cases later.) (v) I'm tempted to recommend the inclusion of the Ordered list tag. I don't remember ever seeing it in a note, but it's fairly common in Wiki pages that editors may be looking at as well. However, opening the floodgates to the html they'll see in those Wiki pages is fraught with dangers. Chavey 04:29, 6 December 2011 (UTC)

Thank you. Your changes are fine with me.

Yes there is redundancy between the unpaired tags section and the stuff about the br tag, one is the general concept and the other is the specifc example, they are intentionally a trifle redundant, IMO most good instructional writing is a bit redundant to drive points home.

You are correct that the formal name for the construct created by the ul tag is "unordered list" but i've never liked that because it isn't unordered, the order of the li items is preserved, it is simply unnumbered.

I thought about including ordered (numbered) lists, but doing so would implicitly authorize use of them in note fields, which I'm not at all sure we want to do. The help pages on wiki editing already describe how to create numbered lists in wiki-code, which is rather different than the HTML ol tag anyway (although it translates into an ol tag for the browser, no one sees that unless they use "view source" on the rendered wiki page).

If I move the nested list after the example it has to be in a subsection of its own, which I thought would lend it undue importance. It is at the end of the description, everything after it is example. But it could be moved if people prefer.

Do you think this is ready to go live? That is, be linked from existing help pages, and perhaps have the "not final" header removed? -DES ^Talk 06:07, 6 December 2011 (UTC)

I'm ok with it, although I agree with Darrah's redundancy comment. My thinking about putting the "unpaired tag" information in the intro section was to keep the tag sections simple -- most people won't need the technical detail, just information about what to do. A suggested revision:

Line breaks are perhaps the most common HTML used in ISFDB note fields, and the only commonly used unpaired tag that is not part of a tag pair.

Simply entering a return into a notes field will not cause a line break to display. A line break can be forced by using a "break" tag. This is often entered as <br />. The closing slash marks the break tag as "self-closing", that is, not part of a tag pair. The shortcut form <br> also works, the closing slash is strictly optional. This is true in all current versions of HTML and all current browsers. Moreover, future versions of HTML are expected to continue to support the <br> form, so editors may use either form in ISFDB note fields.

If you want to keep some of the additional semi-technical information about HTML and browser support, I suggest incorporating it into that new unpaired tags section. --MartyD 11:11, 6 December 2011 (UTC)

Reasonable idea, revision done. Any other comments from anyone? -DES ^Talk 15:26, 6 December 2011 (UTC)