Use of menuchoice tag

Jump to: navigation, search

Do we have a policy regarding use of the <menuchoice> ... </menuchoice> tag? The typographical guidelines mentiones only menu choices. Common practice also includes other named entities in the GUIs, such as buttons, textfields, dialogs etc. I assume this is all OK (IMHO it should be).

Recently I have come across a number of examples, where ordinary reference to things, that can be done in a GUI have also been enclosed in these tags, even though they do not specify a GUI element. An example might look something like this:

Features[edit]

  • does useful stuff
  • change colour and flavour

I think this is potentially confusing and should be avoided. In cases like the above I don't think emphasizing is needed at all, but if some general terms must be emphasized, I think it is preferable to use ordinary bolding.

Should I remove superfluous menuchoice tags when I find them?

Claus chr14:23, 22 September 2010

Yes. I talked to Yurchor about this, this afternoon, see User_talk:Yurchor#x.22Chatty.22_pages_-_hard_to_mark_up__414. Sorry for the extra work.

annew17:34, 22 September 2010
 

Yes. I talked to Yurchor about this, this afternoon, see User_talk:Yurchor#x.22Chatty.22_pages_-_hard_to_mark_up__414. Sorry for the extra work.

annew17:34, 22 September 2010
 

I came across a similar issue within link texts. Link texts already stand out, and adding extra emphasis to words in a link doesn't look good in my opinion. I haven't done anything about these - I know that there are other considerations, such as compliance with docbook, but does that apply to links?

Claus chr09:12, 23 September 2010

I want to stick to compliance with docbook, and I'm honestly not sure of the answer to this. I suspect that the markup within the link may be unnecessary, but I'd like Yurchor to confirm this.

annew11:28, 23 September 2010
 

In fact, there is no such thing as compliance ;)

I have to re-write wiki2docbook to replace <menuchoice> with ''' and parse <keycap>Ctrl+F</keycap> to get <keycombo><keycap>Ctrl</keycap><keycap>F</keycap></keycombo>.

To understand things better, you can compare XML (exported from UserBase and slightly fixed) and DocBook from rekonq pages here, Amarok pages here, and KrossWordPuzzle pages here.

The only thing that is needed for successful conversion is the consistent markup in UserBase itself. Nothing more. There must not be markup like <keycap>OK</keycap>.

The stable rules (and of course, great look of pages) is the only thing that matter for documentation. Should we separate clearer what pages are and what pages are not documentation?

Surely, there is not much sense to prompt someone to use "this markup is a mess!"© just to write their plans on Telepathy, which are far from the real-world implementation. ;)

Thanks in advance

Yurchor12:05, 23 September 2010

[quote]I have to re-write wiki2docbook to replace with '''[/quote] - how useful is <nowiki><menuchoice></nowiki> then? It seems strange to me that I'm going through pages changing "'''" into <nowiki><menuchoice></nowiki> when you have to change them back.

I don't think there's much we can do to help with the keycap parsing, though. Sorry about the "OK" - I think I've only done it once, and it certainly wasn't intentional. I have a bad habit of thinking that I just need to get to a certain point before stopping work, when it would have been better if I had stopped a little earlier.

Maybe we need a thread somewhere more central about which pages need strict markup, and which are better served by just bold and italic carefully applied.

annew17:53, 23 September 2010
 

It is useful. It makes GUI elements on UserBase pages mauch more prominent.

For example, <menuchoice>Ok</menuchoice> gives Ok, but '''Ok''' gives just Ok which is not so visible. If you are trying to follow some instruction the former variant is much better, imho. ;)

I just want to say that DocBook compliance and UserBase markup have to be treated separately.

Yurchor18:48, 23 September 2010
 

That was a very useful clarification. Looking at the docbook code for rekonq, I get the impression, that we should not use emphasis on application names when they appear in the text of a link. Is that correct?

Claus chr05:26, 24 September 2010
 

Yes, it would be better, but emphasizing is not crucial. It can be easily tweaked during final polishing. Just a replace of <guilabel>rekonq</guilabel> with "&rekonq;".

The most ugly thing is to use bold typeface or <menuchoice> in section headers, or bold in {{Warning}}. Can it be added to Guidelines?

Thanks.

Yurchor13:13, 24 September 2010

Yes, I'll do that. I guessed that it was better not to use it in section headers (I left some in because they were originally there, and I wasn't sure) but I wouldn't have thought of leaving it out of the templates - I assume that the same applies to Information, Notes and Tips templates.

annew15:12, 24 September 2010
 
 
 

Sorry to keep going on about this issue, but today I encountered some difficult problems translating KrossWordPuzzle. There are several problems all related to the use of the menuchoice tag.

First, It seems to me to be potentially confusing to ordinary readers to use the menuchoice tags for anything other than actually explaining how to do some task using the GUI. If we use menuchoice tags the way the are used in the feature list of KrossWordPuzzle, readers may confuse what is merely a list of capabilities with a discription of how to actually accomplish something (and be frustrated because the don't understand the "directions").

Secondly, using the name of a GUI element in its "literal sense", fx treating Open as a verb, is going to cause problems to many translators. The great differences between the various grammatical systems would force translators to write awkward (perhaps even ungrammatical) texts.

Thirdly, we can never be sure, that a translation of the GUI even exists. If it doesn't, a translator of the UserBase page may need to have English words in the translation. Here I am assuming, that the name of a GUI element should always appear in print exactly as it is shown on the screen, which seems highly desirably to me.

Therefore I would recommend that names of GUI elements are avoided in feature list and similar places where we are talking about the capabilities of an application, but not about how to accomplish anything in detail. Perhaps the simplest way to think about this is to allways treat the thing enclosed in a menuchoice tag as a proper name. Would it be a good idea to add something like this to the guidelines or are there better ways to deal with the problems?

Claus chr16:09, 25 September 2010

I did say that you might find other pages that were written before I had had the conversation with Yurchor. The best thing to do is simply point me to them, and I'll fix the problems. I'm dealing with so many pages that I can't possibly remember which pages might be affected, so you will just have to prompt me. Sorry.

annew17:07, 25 September 2010
 

Actually, my latest complaint was about yet another kind of problem with the use of the menuchoice tags. The KrossWordPuzzle page did not "abuse" the tag in the way we talked about earlier, but I still think that the way menu items were referenced is unfortunate. I'm sorry I didn't make that clear enough.

Claus chr06:38, 26 September 2010
 

Thirdly, we can never be sure, that a translation of the GUI even exists. If it doesn't, a translator of the UserBase page may need to have English words in the translation. Here I am assuming, that the name of a GUI element should always appear in print exactly as it is shown on the screen, which seems highly desirably to me.

I do not think it's a good idea to translate manuals for the applications with untranslated interface. Anyway, KrossWordPuzzle has not been translated to Danish yet. I cannot even to contact with the developer to ask him is it worth to put DocBook in the main SVN module, but that's the different story. ;)

To keep the good translations, I asked that screenshots can be translated, not as in Amarok Quickstart. It will be LP-quality translations of manuals if translators never use the applications. ;)

Yurchor16:52, 25 September 2010

This author was active for a good while, but seems to have disappeared at the moment. I too tried to contact him. His apps are nice. I don't want to lose them.

I've re-marked the KrossWordPuzzle page. No guarantees that it's right, but of course you are free to edit as necessary.

The typographical guidelines are fairly straightforward to document. I'm beginning to think that we need a separate page for the actual markup for translations, and to ask translators to join the Talk page to help work out rules. I'm clear on straightforward decisions, but less formal pages are very difficult for me, and therefore I am not likely to write a good guideline for this.

I wasn't aware of the problem with the Amarok QSG pages - and there are a lot of them. I'll try to fix those over the next few days.

annew17:36, 25 September 2010
 

I agree that we should have a translation of the GUI before we begin translating the manual. I'm not so sure that the same always applies to traditional UserBase application pages, though.

Claus chr06:51, 26 September 2010
 

Another question came up regarding the way we emphasize applications. The problem comes up in the genitive case: Where in English we would have fx "The Amarok menues ..." og "Amarok's menues ...", the proper Danish translation would be "Amaroks menuer ...", i.e. the same as the latter English form but without the apostrophe. Is it desirable to keep the s ending unbolded (it does look a little odd)?

Claus chr16:46, 27 September 2010

Having had time to think about this, I think you are right. In future I will mark the whole word in bold. Please correct any instances you find meanwhile. Thanks.

annew10:23, 30 September 2010