Wikipedia talk:Manual of Style/Glossaries

From Wikipedia, the free encyclopedia
Jump to: navigation, search
Shortcuts:
          This page is of interest to the following WikiProjects:
WikiProject Manual of Style
WikiProject icon This page falls within the scope of WikiProject Manual of Style, a drive to identify and address contradictions and redundancies, improve language, and coordinate the pages that form the MoS guidelines.
 
WikiProject Glossaries
This article falls within the scope of the WikiProject Glossaries, a collaborative effort to improve the coverage of Glossaries on Wikipedia. If you would like to participate, please visit the project page, where you can join the discussion and see a list of open tasks.
What is a glossary? It's a specialized type of annotated (stand-alone) list article, where the annotations are descriptions of the terms listed. Glossaries serve the primary functions of lists as well as present definitions to assist topic identification, link selection, and browsing. List structuring and annotation is covered in WP:LISTS, and glossary formatting is covered at Wikipedia:Manual of Style (glossaries).
 

Manual definition lists / Hierarchical Non–glossary lists / Non–Non–structured lists[edit]

Resolved: (Apparently.) Mostly moot; one issue is Won't fix; any others lost in the TL;DR.

Regarding §Non-glossary lists using glossary formatting and §Actual XHTML output of structured glossaries, a few are things are confusing, perhaps until WP:LIST#Definition lists gets updated? I'm not sure if the plan is to keep "Non-glossary lists" in other sections of this article... Because {{term}} & {{defn}} insert class=glossary It would seem that "manual" HTML is currently the only way? (I find it easier any way). The article makes "wikimarkup equivalent, the leading ;" sound scary. Also, because the output is the same, it's unclear why {{term}} should not be used.

The {{term}} template should only be used for actual glossaries. For non-glossary lists that simply use glossary formatting, use a bare <dt>...</dt> structure, or its wikimarkup equivalent, the leading ; character:

  {{gloss}}
  ;term 1
  :Definition of term 1.
  {{glossend}}

Shouldn't it be this?

  {{gloss}}
  {{term|term 1}}
  {{defn|Definition of term 1.}} 
  {{glossend}}

Or this? (per class≠glossary)

  <dl>
  <dt id="term 1">term 1</dt>
  <dd>Definition of term 1.</dd>
  </dl>

Somehow, I got the impression a linkable anchor would be automatically inserted when using <dt>...</dt> so that it's equivalent to {{term}}. It seems I got confused, (it's not automatic). Using span tags are mentioned but they don't seem to work inside a <dt>...</dt>, so maybe it should recommend adding an id attribute? (or the {{anchor}} template, if possible, and more than one link target is required)?

Possibly in §Technical notes it should mention that it's not referring to the "manual" HTML markup in item 4, (unless it's somehow related):

4. Forthcoming: When a known MediaWiki bug is fixed, so that the [X]HTML element <dfn> is properly supported, the {{term}} template will also identify the term as the defining instance of its usage in the page.

In the §lead, second paragraph, should it read?

Glossaries can be formatted in a structured, non-structured or manual html manner, each of which can appear much the same to the human reader. Glossaries can be stand-alone list articles or embedded in-article list sections; either may be structured non-structured or manual html. (Glossaries can constructed as flat list or hierarchically as well). There are thus six (or twelve) basic types of glossary on Wikipedia. Regardless of the type selected, there are guidelines for making them useful, consistent, reader-friendly, and editor-friendly. There are also rationales for selecting which type to use.

I just wanted to touch on one last thing in §Alphabetization, is it necessary to dictate "Alphabetize term entries from A to Z"? Hierarchical lists, for example, might not necessarily be sub–sorted alphabetically at each level, and the hierarchy itself could be informative for the reader—without insisting on strict determinism for each of its parts. WP:LIST#Definition lists seems to be a little more circumspect. One hopes the order in which a flat glossary should be sorted could go without saying... Machine Elf 1735 (talk) 10:06, 2 August 2010 (UTC)

  1. Most of this is moot, due to more recent major editing.
  2. If someone wants a generic version of the template with no class parameter or a different value because they don't like the style applied by class="glossary" (which is none at all; it's simply reserved), they can copy the code, paste it into Template:Dl-dl, and take out/change the class, and do the same with matching Dl-dt and Dl-dd templates if they want. There's no reason to make the glossary template either more complicated or dumbed down.
  3. If there are other out-standing issues, please raise them in new threads, one issue at a time, not in a long post raising multiple issues, or my asplode (not that I personally WP:OWN this stuff, of course, but I wrote 95% of it, and understand it better than anyone else, both as to the tech and as to the purposes, so if there's a problem it'll probably be me fixing it). — SMcCandlish   Talk⇒〈°⌊°〉 Contribs. 00:00, 12 February 2012 (UTC)
Why would “someone want a generic version”? “because they don't like the style ... which is none at all” in other words, you want people to copy a bunch of your templates for no particular reason… I agree, that can neither more complicated nor dumb. Could there be any doubt you “understand it better than anyone else”? No, no problem that I'm aware of requires you to be fixing it. Certainly, henceforth, I shall provide each WTF individually, as you require. How gracious that years later you've called my attention to the fact that until now, you completely ignored it. Indeed, TL;DR is moot, and fair enough, the “asplode” of TL;DR barely covered 5% of the page's preaching, confusion and lousy advice. But my apologies, how presumptuous: you're on the dispensing end of the advice.—Machine Elf 1735 12:59, 12 February 2012 (UTC)

Taking advantage of semicolon-colon Wiki markup[edit]

Resolved: MediaWiki's parser is badly broke on this; the italics problem has been fixed at MediaWiki:common.css.

Bravo on these efforts to standardize glossaries and make them accessible. I have one suggestion, however: doesn't it make sense to take advantage of the nifty Wiki markup for association lists as much as possible? The semicolon-colon markup does almost everything we want it to do here, as long as the "terms" get wrapped with <dfn>..</dfn> tags. Thus, for example, the following Wiki markup:

;{{term|term 1}}
:Term 1 definition
;{{term|term 2}}
;{{term|alternate term 2}}
:Term 2 definition 1
:Term 2 definition 2

renders, upon parsing by MediaWiki (assuming that the "term" template simply wraps <dfn>..</dfn> tags around the term:

<dl>
<dt><dfn>term 1</dfn></dt>
<dd>Term 1 definition</dd>
<dt><dfn>term 2</dfn></dt>
<dt><dfn>alternate term 2</dfn></dt>
<dd>Term 2 definition 1</dd>
<dd>Term 2 definition 2</dd>

which is a perfectly accessible HTML 4/5 association list. In fact, the <dfn> tag is so unobtrusive, that I don't think it is asking too much of editors to simply do the following, to the same effect:

;<dfn>term 1</dfn>
:Term 1 definition
;<dfn>term 2</dfn>
;<dfn>alternate term 2</dfn>
:Term 2 definition 1
:Term 2 definition 2

which is almost as simple as using the template format. All the matters of style could be handled in MediaWiki:common.css or any of the various skins. If we want to present the glossary in a particular style, it could be wrapped in the "gloss" template, and then styled in the css style sheets. For example, the style sheet could define an html class in which the terms are on the same line as the definitions. That way, the styling is completely separated from the content, and different Wikipedia skins can present the glossaries differently.

By the way, now that the <dfn> tag is recognized by Wikipedia, I have just added some default styling for the tag in common.css. As it now stands, adding a <dfn> tag within the <dt>...</dt> tags of an association list does not change the default styling, which is bold, no italics. In other words, including the <dfn> tag to designate the "names" in an association list as being a "defined term" does not unexpectedly convert the terms to bold italics. COGDEN 19:54, 4 May 2011 (UTC)

I spoke too soon. The formatting I added to common.css is apparently controversial (at least for now), and has been removed. The consequence of this is that <dfn>-tagged terms within glossaries will show up as bold italics in Internet Explorer, Firefox, Opera, and Safari, but will show up as just bold in Chrome. This happens if you use the "term" and "defn" templates as well. If that's not what you want, then please speak up at MediaWiki:common.css. COGDEN 03:01, 10 May 2011 (UTC)
See Wikipedia:Manual of Style/Glossaries/DD bug test cases; the entire point of all this templating is that MediaWiki's parser is badly broken when it comes to ;/: markup. I have no idea what they're doing with making <dfn>...</dfn> do weird stuff; it shouldn't have any style whatsoever, it's pure semantic metadata. I've used {{dfn}} to undo this with local style, and this fix propagates to {{term}}. I've filed an editprotected at MediaWiki:common.css to permanently fix the italics problem. — SMcCandlish   Talk⇒〈°⌊°〉 Contribs. 23:28, 11 February 2012 (UTC) Update: The italics fix is now in common.css. — SMcCandlish   Talk⇒〈°⌊°〉 Contribs. 23:33, 16 February 2012 (UTC)

Revamp begun[edit]

I've begun simplifying the instructions, focusing them on the 3 styles of glossary format. I've shortened the styles' names, for easier reading. I've removed the term "structured", so it won't get confused with the phrase "structured list", which refers to outlines.

I've removed a lot of redundancy from the page, but there is still a lot more in there. Sometimes things are explained 2 or 3 times.

For some unknown reason, the Terminology section (an embedded glossary) wasn't following the guideline. It does now.

My eyes have glazed over, so I'll give it a rest for a day or two and will return to continue copy editing for clarity and conciseness.

We need to get some proofreaders to critique it, preferably some who have never built glossaries before. The Transhumanist 04:32, 1 February 2012 (UTC)

I put a few snippets back in because they're important for reasons that may be orthogonal to your concerns, but overall agree with the changes, and it's nice to have someone else paying attention, as well as adding stuff I didn't think about, like material on the Outlines. Not sure how I feel about losing things like "the importance of getting basic information into an article and sourcing it greatly exceeds any formatting considerations", etc., but have left all that out. The stuff I put back was largely technical or in a few places things like "If a glossary consists of few entries, all with lengthy definitions, consider instead formatting the article as a subheaded-style glossary, in regular paragraphs.", because it isn't safe to assume that everyone will read the entire page top-to-bottom, so it needs sectional cross-references. PS: Nice edit summaries, too; helped me grok what you were doing and why. — SMcCandlish   Talk⇒〈°⌊°〉 Contribs. 22:55, 11 February 2012 (UTC)