Help talk:Using Templates and HTML in Note Fields

A number of comments were made on the community portal as this page was being drafted and revised. Those comments have been copied here so that they will remain associated with the help page. Further discussion of how to improve the page can take place in added sections below these. -DES ^Talk 14:33, 22 July 2012 (UTC)

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 "is considered poor style" in a guide to writing HTML. Just because is required in XHTML, that doesn't mean isn't proper HTML. Or maybe things have changed since I learned HTML. Will HTML5 require a slash to close single tags (like 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 or similar formations, as I understand it. Current texts on HTML discourage the form. However, I just looked through the HTML5 docs in some detail, and found that it considers to be normal. I will change the text. -DES ^Talk 04:42, 5 December 2011 (UTC)

BTW HTML5 is treating as a paired tag, with the end of the paragraph to be marked with . 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 vs. . I think the current wording is still misleading. In particular, you write "However future versions of HTML are expected to support the form", which sounds as if earlier versions did not support the 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 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)

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  . ~~The closing slash marks the break tag as "self-closing", that is, not part of a tag pair.~~ The shortcut form   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   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)

Pass 3

Copied from ISFDB:Community Portal#Help for HTML in note fields -DES ^Talk 14:29, 22 July 2012 (UTC)

Last December I drafted Help:Using HTML in Note Fields and revised it in accord with some suggestions from various editors, but there wasn't, as I recall, a clear consensus to remove the "not final" header and link this from other help pages.

Does anyone object to this going "live" and becoming as final as any of our help pages ever is? Does anyone have any further suggestions for it? -DES ^Talk 18:41, 8 July 2012 (UTC)

Looking at this page again, I object. I think these instructions are weighted much too heavily to the unnecessarily technical approach to using HTML, and are bad advice to editors whose interest lie more towards the SF and less towards being an HTML geek. For example, it says "it is a very bad idea to use the less than (<) or greater than (>) signs in your note text, because the browser may mix them with tags." This is absurdly rare. The possibility that a normal person would write something with a < or > sign that is confused for a tag by a browser is essentially zero. Chavey 19:47, 8 July 2012 (UTC)

You would think so. There was an editor a couple of years ago who liked to use the character (>) as a pointer, and I had to stop him because his records came up as errors in the Potential HTML Errors in Publication Notes script. (BTW, how many other moderators run these scripts other than Bill Longley and me?) Mhhutchins 19:58, 8 July 2012 (UTC)

The page also argues for using lines using the <li>Copyright 1984 by Jane Jones.</li> format. There is NO reason to use the </li> tag, except to make your Note harder to read by other humans. It is unnecessary, not required by any version of html, never will be required by any version of html, and in the small amount of space we have for editing notes, serves only to make the actual text harder to read. The same statement is true for the recommendation of instead of . The ONLY reason to do that is to say you're more of an html geek than someone else is. Your statement that "This is often entered as " is completely false on ISFDB -- almost everyone uses the simpler . For unnumbered lists, you only recommend the use of the <ul><li></li><li></li></ul> format, whereas by at least a 3 to 1 margin, existing ISFDB editors use the • • format, which uses 1/3-rd as many html tags as your recommendation, and has essentially the same list appearance.

There are many parts of this page which are very good, and will be quite helpful to editors. However, it is written in such a way as to make it much harder for the html weak (or illiterate) editor to do the simplest of our common tasks. Chavey 19:47, 8 July 2012 (UTC)

I agree that the instructions concerning and </li> are unnecessary. But I use the HTML for unnumbered lines in ALL of my notes, and never use • which was popularized by one prolific note editor, and picked up by others. Either way, that's a matter of preference, not style. Where did the 3 to 1 statistic come from? Mhhutchins 19:58, 8 July 2012 (UTC)

(My comments here moved lower) Chavey 04:24, 9 July 2012 (UTC)

Please note this recent exchange in which a > character did in fact cause a problem, which is what prompted me to add this section. -DES ^Talk 20:05, 8 July 2012 (UTC)

I linked to that discussion in my response to Darrah above. Thanks for adding the part to the Help page about using that character in the Note field for a non-HTML purpose. Mhhutchins 20:21, 8 July 2012 (UTC)

That link wasn't yet present, or i failed to see it, when i wrote the above. There have been multiple edit conflicts in this exchange. -DES ^Talk 20:29, 8 July 2012 (UTC)

As to the and </li> forms, they are out there. (I am NOT the only editor who uses them routinely, I believe. In any case I do use them routinely.) Editors will see them, and should be able to find out what they mean. Moreover, I do not "only" recommend these forms. I specifically say "Therefore closing </li> tags may be used or omitted in ISFDB note fields as each editor prefers, there should be no difference in the resulting display." I make a similar comment about tags. I can add an example without the </li> tags if you like. -DES ^Talk 20:27, 8 July 2012 (UTC)

I have added such an example, so a user can use it as a model if desired. I have also changed "often" to "sometimes" in mention of >br />.

I admit that I expect a future version of HTML to deprecate these (unclosed) forms, but it will be years if ever before a browser won't accept them. -DES ^Talk 20:10, 8 July 2012 (UTC)

As to making it "harder for the html weak (or illiterate) editor" to do things, I expect that such an editor will use copy, paste and modify either from this help page or from an example s/he finds and likes. The difference in effort in copying a model with or without </li> tags is essentially zero, that is all subsumed in the initial paste. As to "the small amount of space we have for editing notes" the permitted length of a note field is, i understand, far longer than any sensible note would ever be, even in the most verbose possible HTML. As long as a single line of the note shows in the edit window (which scrolls), there should be no problem -- and many records will have notes which require scrolling, even with nothing but br tags. I don't think your arguments have any weight. -DES ^Talk 20:27, 8 July 2012 (UTC)

Oh, I might add, the "browser may mix them" language is straight from the w3schools page on HTML entities, to which i link. -DES ^Talk 20:36, 8 July 2012 (UTC)

I've just looked over the help page and can't find anything of substance to object to. Any reasonably intelligent editor, without any knowledge of HTML, should be able to start using it after looking over these instructions. If not, that's what moderators are for (ha!). I see no reason why the page can't go "live". But let's wait for a consensus before doing so. (There's a couple of typos that I'll clean up in the meantime.) Mhhutchins 21:00, 8 July 2012 (UTC)

Thank you, awaiting further comments. -DES ^Talk 21:10, 8 July 2012 (UTC)

The copy editor in me came out, so I did a few more changes for clarity, and added an example of an OCLC link. Mhhutchins 21:59, 8 July 2012 (UTC)

One issue with the copyedit: You added the text "MLA (Modern Language Association) Style requires that book and magazine (container) titles be entered using italics, while essay and story (contained) titles be entered using standard parentheses." to the section on boldface. But the ISFDB does not, as far as I know, use MLA style. For mentions of works in notes, I (and I think most other editors) follow the more general convention of placing titles of shortfiction and essays in "quotes". All or almost all, uses of boldface I have seen in ISFDB notes are there to emphasize specific words, not to mark of titles or other parts of citations. One or two editors seem to do this with some frequency (and I think used to do it more often), most others rarely if ever use boldface in notes, except maybe in a note such as "Do not merge collection X (1928) with collection X (1932): they are not the same work." Thus the mention of MLA format has little or nothing to do with the use of boldface. I suggest removing this text. -DES ^Talk 05:26, 9 July 2012 (UTC)

It was a momentary brain fart. Of course, I should said that contained titles should be in quotes, not parentheses. I'll change that immediately, but I still think it's worthy of mentioning MLA Style in that part of the help section to discourage editors to use of bold markings for titles. And believe me, David, I've seen enough submissions that do exactly that. There are hundreds verified by Dragoondelight and other editors throughout the database. Mhhutchins 06:04, 9 July 2012 (UTC)

Some data points on what we actually do: There are 68,234 publication records that use for their Note line breaks (or at least some of their line breaks). There are 21,797 records that use the < li > format. That's more than a 3 to 1 preference for over < li >. The Advanced Search doesn't allow me to search for the bullet character, so I can't tell how many of the former use the bullets as well. Personally, I like both the • form and the < li > form, and think we should document them both. The part that annoys me is the use of the unnecessary < /li > and tags. Only 3,334 of the records that use < li > also use the unnecssary line ending tag, i.e. about 15% of them. There are 4,075 pub records that use the spurious "/" with . That's less than 6% as many records as use the simplified form. I see no reason to appear to be recommending unnecessary complexity over simplicity. Chavey 04:24, 9 July 2012 (UTC)

Very well, you have established that the form is significantly more common than the form in existing ISFDB notes, that the is more common than than the < li > form, and that the majority of its uses do not use closing < /li > tag. You have also documented that there are thousands of notes that do use the , and < /li > forms, and tens of thousands that use the < li > form. Therefore editors will, sooner or later, encounter these forms, and they should be documented on the page. I believe that the page as it now stands does not "recommend" any of these forms over another -- it documents the and , forms, and explicitly states that their output is identical, allowing editors to chose for themselves. It does not even give any arguments for choosing the form. Similarly, it documents the < li > and < li >< /li > forms with examples of each, and again explicitly says that their output is identical, with nary an argument for one over the other. I don't see any harmful recommendations here -- what would you suggest I change? Would you have me remove documentation of the and < /li > forms altogether? That risks confusing people when they find forms not documented. -DES ^Talk 05:07, 9 July 2012 (UTC)

I admit that i do not like the • form, for two reasons: 1) it requires using a character not available on the ordinary keyboard, which must be entered via the alt-number interface, or via character map or a similar tool, or by copying from a template. Any of these adds trouble for no gain, IMO. 2) it doesn't wrap properly if a list item is longer than a single line, which is common in notes, particularly when a cover image has reduced the available width for the display of the publication data, including the notes, as is often the case. A true list (using li) wraps the second line of text flush with the start of the first, whereas the • form wraps the text under the bullet above. Therefore I discourage this form. If you want I will add documentation of this form to the page, but if I do I will mention these issues, since they are practical and not merely stylistic. -DES ^Talk 05:07, 9 July 2012 (UTC)

For similar reasons, I also dislike the user-created bullet. Regardless of my feelings toward it, there's no reason whatsoever to explain how to do it on a page that instructs editors how to enter HTML in an ISFDB record's note field. I firmly believe its use arose from an editor, seeing an HTML-derived bullet, thought that alt+7 was the way to enter a similar bullet into the note field. Mhhutchins 06:22, 9 July 2012 (UTC)

By the way, i wonder what would be shown if we had a time-stamp of each of those note fields? Would the use of one form be more common in recent notes than in older ones? I suspect that the li forms have increased significantly in recent years relative to the br forms. However I can't document this, and I doubt that queries on the db could easily determine it one way or the other. -DES ^Talk 05:07, 9 July 2012 (UTC)

So, what changes would you suggest to the page as it now stands? I presume we both want to make this page as useful as possible to ISFDB editors with no or limited experience with HTML. -DES ^Talk 05:07, 9 July 2012 (UTC)

David, I think you've made a good case about retaining the HTML options on the help page, regardless of the frequency with which either one is used. Darrah, I'm puzzled why you feel that there should be no mention of any option other than the most popular usage. The wording is quite neutral and doesn't push one over the other. Like David, I hope you (and others) might come up with constructive suggestions. Let's hope that our "fluency" in HTML isn't clouding our judgement here. Mhhutchins 06:04, 9 July 2012 (UTC)

The proposed text looks fine to me. As for  • , I think we should actively discourage its use and allow/encourage conversion of it to <ul><li></li></ul> (whether the list entries are closed or not is beside my point). There are two minor reasons for this:

Browsers will auto-indent wrapped list entries so that subsequent visible lines due to wrapping are left-justified under the start of the previous line's text. The • method will not do this, with wrapped lines left-justified to the outer edge.
Browsers will automatically choose an appropriate bullet character. Nested lists will get different bullets to make them more easily distinguishable from one another. In fact, the "Notes" section already appears in a bulleted list. Hard-coding any character can defeat that useful behavior.

Yes, raw HTML editing is probably something only a geek (and I'm one) could love, but I think most people will be able to follow the help without too much difficulty. --MartyD 10:36, 9 July 2012 (UTC)

I'm not a big fan of HTML in notes as it makes things harder to read offline, when I'm looking for notes in the database backups. I do use but follow it with a carriage return as well, which works as a nice compromise. I'm particularly against using it to highlight individual words as searches may miss it - e.g. "Do not merge" and "Do NOT merge" are different. As for "•", I never use it but don't actually remove them. BLongley 11:01, 9 July 2012 (UTC)

You are correct, Bill, that searches may be affected by HTML tags in notes, but then they can also be affected by varieties of wording, and a good search will take account of this. If you search for 'merge' you will find both "Do not merge" and "Do NOT merge". If you search for 'not merge' you won't find the second, but you also won't find "don't merge", "do not ever merge" "be sure not to merge", "should not be merged" and the like. Anything that finds all or most of these will also find "Do NOT merge", I think. -DES ^Talk 17:06, 9 July 2012 (UTC)

And would also find "PLEASE MERGE!" left by an editor that hasn't coped with the complexities of that yet. (There are enhancements in the pipeline to make merging more intuitive and less likely to cause loss of data.) I'm looking a bit far ahead - I'm not sure how many users have even noticed the comparatively new ability to search notes - but I can already foresee some of the problems. BLongley 19:43, 9 July 2012 (UTC)

(Unindent) there have been no comments for 10 days now. Any further suggestions or requests for changes or other comments before I take this live? -DES ^Talk 15:21, 19 July 2012 (UTC)

Help talk:Using Templates and HTML in Note Fields

Contents

Pass 1

Pass 2

Pass 3

Navigation menu

Search