GNOME Bugzilla – Bug 736212
gnome-user-docs quotes parts of filenames incorrectly
Last modified: 2014-09-20 13:03:05 UTC
After discussion on #docs it appears that the correct choice is to use <key>.</key> when referring to periods at the beginning of a filename. Some parts of the documentation doesn't adhere to this however. By the same reasoning ~ and * and ? also ought to use <key></key>. Currently some places use <file></file> and others use "", both of which are not the best choice.
Created attachment 285597 [details] [review] Proposed patch.
use consistent markup for punctuation in filenames
<key> should be used for keystrokes. For example, a key in a keyboard shortcut. I wouldn't use it when talking about a character which makes up part of the filename as the context is quite different. I think <file> is more appropriate for parts of filenames as the markup should be consistent regardless of whether it is a partial or a full filename. On the other hand, if the aim is to emphasise some part of text, emphasis (<em>) is another option.
Using <file> was my original idea: 19:47 < sebras> I think the right approach is to use <file>.</file> and <file>~</file> instead of <key>.</key> and <key>~</key>. 19:55 < mdhill> sebras, I think <key> is more correct because it refers to a single character on the keyboard 19:58 < sebras> mdhill: ok, but in that case do you also advocate using <file>.</file> in files-lost.page? 19:58 < sebras> mdhill: I'm happy either way as long as it is consistent. :) 19:59 < mdhill> yes, good catch And despite this discussion I still find that my original patch has been applied https://git.gnome.org/browse/gnome-user-docs/commit/?id=96b041ba320422ead71393c60a3cfae6ccb4be9e What gives? Do you want me to provide another patch to consistently use <file> instead? I'm happy to do so but I'll wait until the discussion has settled. :)
Hi Sebastian, having seen it, I agree it looks better with <file> tags. Can you please provide another patch? Sorry for the indecision.
Created attachment 285681 [details] [review] Change consistently used tag. This one basically reverts the previous patch and improves upon it.
If it helps, projectmallard.org has a nice summary of how inline elements should be used (and a lot more detail if you want it too): http://projectmallard.org/1.0/mal_inline#elements I think that it's important to use the markup according to intent in case the styling ever changes. As for the styling of specific elements, if you think of a way to improve it, please file a bug or patch :)
Comment on attachment 285681 [details] [review] Change consistently used tag. Pushed to master in commit c3e17c46dda32738186f7f45b8d615775309d9fd Thanks for the patch!