Re: proofreading the installation-guide
Holger Wansing wrote:
> Justin B Rye <justin.byam.rye@gmail.com> wrote:
>> An interesting idea, but one that seems unlikely to work, especially
>> given the way it's used in the text. For instance, there's a page
>> "welcome/what-is-debian-linux.xml", which is full of sentences like
>> "&debian; was the first Linux distribution to include a package
>> management system".
>
> It was mostly me changing Debian into &debian; that days in 2010.
> If I remember correctly, it was initiated by a post of Frans Pop,
> who proposed that change. And the rationale was in fact, to get a
> manual, that can easily be turned from a "Debian installer manual" into
> a "Ubuntu installer manual", for example.
Whoever it is that's reworking the manual for the derivative is still
going to need to go through the whole text changing the content. The
&debian; entity seems liable to cost us more effort than it saves them
(a single extra search-and-replace operation).
>> And I can't see any particular pattern in when it's "Debian
>> installer", when it's "&debian; installer", and when it's "&d-i;".
>
> With the above been said, it should be as follows:
> In sentences which apply to Debian and also to its derivates, it should
> use &debian; ,
> while in sentences which only apply to Debian and not to the derivates,
> it should be Debian.
>
> It was also my intention to make it that way indeed, but:
> 1. I found out that the job was bigger than I first thought when taking it
> over, leading to mistakes.
> 2. due to the lack of manpower in the d-i team, especially the loss of Frans,
> the d-i manual guru (amongst other roles), there was probably not enough
> reviewing of that changes, and things may got overlooked.
Oh, well, for now I'll plan on trying to get &debian; into shape as
part of my proofreading sweep - it would be easy enough to switch back
from sometimes saying "&debian;" to always saying "Debian" if we
decide to give up on it.
>> The "&debian-gnu;" entity is effectively just shorthand for "Debian
>> GNU/&arch-kernel;" - confusing but handy.
Wait, does it expand to Debian or &debian;?
>> The "&architecture;",
>> "&arch-title;" and "&arch-kernel;" entities are slightly oddly named
Since I keep losing track and having to check again, I'll leave a note
for myself here:
"&architecture;" = "32-bit PC", "32-bit soft-float ARM", etc.
"&arch-title;" = "i386", "armel", etc.
"&arch-kernel; = "Linux", "KFreeBSD", etc.
>> but make sense as parametrisations, as do "&release;" and
>> "&releasename;" as long as they're used for things that stay true for
>> every release. (Oh, and I've just noticed there's a
>> "&releasename-cap;", used instead of plain "&releasename;" for no
>> obvious reason in "hardware/supported/arm.xml" and nowhere else.)
>>
>> But there are also special entities for "&enterkey;", "&escapekey;",
>> "&tabkey;", "&f10key;", and even "&ekey;"! Most of these are only
>> used once each - the rest of the time (and always for keys like "F2"
>> or "space") it just uses "<keycap>...</keycap>".
>
> That entities like
> &releasename-cap;
> &enterkey;
> &escapekey;
> &tabkey;
> were created, to give translators a chance to follow the rules for their
> language there (for example, in German we write Jessie, Stretch or Unstable
> uppercase, while in English that's mostly lowercase: jessie, stretch, unstable)
> or to have "tab key" translated into "Tabulator-Taste" for German, for
> example.
Sorry, I don't follow. Surely German needs *all* instances of
&releasename; to be capitalised? How does it help to have some of
them replaced in the text with &releasename-cap;?
And why is it any easier to provide translations for &tabkey; than for
<keycode>Tab</keycode>? Why would you need ones for &f10key; and
&ekey;, but not <keycode>F2</keycode> or <keycode>Space</keycode>?
Hmm, I can imagine cases where the *English* version might benefit
from having an entity &indefinitearticle; that automatically selects
either "a" or "an" depending on whether the following substituted-in
word starts with a vowel sound! But let's not.
> Globally said, there may be several occurrences of above things not
> being perfectly consistent, because there are many editors for the manual
> these days, but there is no Frans Pop anymore, watching the changings and
> correcting things where needed.
>
> [PS included for convenience:]
> So I suppose it would be reasonable to put a comment in the document
> source explaining this, perhaps where these macros are defined, and
> making further changes as we discover the need and have time, possibly
> prompted by bug reports from Debian derivatives or forks, or even just
> doing a diff between our d-i manual and some of the derivatives'
Okay.
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
Reply to: