Re: proofreading the installation-guide
On Tue, Jul 28, 2015 at 07:00:27PM +0200, Holger Wansing wrote:
> 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.
>
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'
-- hendrik
Reply to: