Re: proofreading the installation-guide
On Tue, Jul 28, 2015 at 09:06:03PM +0100, Justin B Rye wrote:
> 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).
If that was the case, it would be a single search-and-replace operation
for you, too.
Just catch the ones you see while proofreading, leave the rest.
The Debian derivative's people will catch the ones you miss, and you
can someday, *when there's time to do it*, diff your source with
theirs to find the rest.
Of course, this is only for derivatives that use the same installer.
>
> >> 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
>
>
> --
> To UNSUBSCRIBE, email to debian-boot-REQUEST@lists.debian.org
> with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
> Archive: [🔎] 20150728200603.GA13289@xibalba.demon.co.uk">https://lists.debian.org/[🔎] 20150728200603.GA13289@xibalba.demon.co.uk
>
Reply to: