Re: proofreading the installation-guide
Hi,
Justin B Rye <justin.byam.rye@gmail.com> wrote:
> Hendrik Boom wrote:
> > Justin B Rye wrote:
> >> * &entity questions - when am I meant to say "Debian" and when is it
> >> "&debian;"? This like many of these entities seems to have no
> >> obvious function other than to make the source harder to
> >> interpret...
> >> * The &d-i; entity expands to "debian-installer" in bold verbatim
> >> lowercase. If that is in effect the brandname of the software
> >> project then presumably we shouldn't be talking about "the
> >> &d-i;" - that ought to be "the Debian installer".
> >
> > Presumably both of these parametrisations are for the convenience of
> > Debian derivatives and forks. By making these macros, it's easier for
> > the, and it'll be easier for us to merge downstream patches.
>
> 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.
> 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.
> The "&debian-gnu;" entity is effectively just shorthand for "Debian
> GNU/&arch-kernel;" - confusing but handy. The "&architecture;",
> "&arch-title;" and "&arch-kernel;" entities are slightly oddly named
> 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.
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.
Regards
Holger
--
============================================================
Created with Sylpheed 3.5.0 under
D E B I A N L I N U X 8 . 0 " J E S S I E " .
Registered Linux User #311290 - https://linuxcounter.net/
============================================================
Reply to: