[PATCH] Documentation typo.

[PATCH] Documentation typo.

[Pierre Habouzit]

From: Pierre Habouzit <pierre.habouzit@m4x.org>

Signed-off-by: Pierre Habouzit <madcoder@debian.org>
---
 Documentation/pull-fetch-param.txt |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt
index 8d4e950..5bcdbc8 100644
--- a/Documentation/pull-fetch-param.txt
+++ b/Documentation/pull-fetch-param.txt
@@ -4,7 +4,7 @@
 
 <refspec>::
 	The canonical format of a <refspec> parameter is
-	`+?<src>:<dst>`; that is, an optional plus `+`, followed
+	`\+?<src>:<dst>`; that is, an optional plus `+`, followed
 	by the source ref, followed by a colon `:`, followed by
 	the destination ref.
 +
-- 
1.5.2.1

Re: [PATCH] Documentation typo.

[Junio C Hamano]

Pierre Habouzit <madcoder@debian.org> writes:

> From: Pierre Habouzit <pierre.habouzit@m4x.org>
>
> Signed-off-by: Pierre Habouzit <madcoder@debian.org>
> ---
>  Documentation/pull-fetch-param.txt |    2 +-
>  1 files changed, 1 insertions(+), 1 deletions(-)
>
> diff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt
> index 8d4e950..5bcdbc8 100644
> --- a/Documentation/pull-fetch-param.txt
> +++ b/Documentation/pull-fetch-param.txt
> @@ -4,7 +4,7 @@
>  
>  <refspec>::
>  	The canonical format of a <refspec> parameter is
> -	`+?<src>:<dst>`; that is, an optional plus `+`, followed
> +	`\+?<src>:<dst>`; that is, an optional plus `+`, followed
>  	by the source ref, followed by a colon `:`, followed by
>  	the destination ref.
>  +

Not really.  I suspect you are using AsciiDoc 8?

Your patch does make AsciiDoc 8 keep '+' in the HTML output, but
manual page output gets an extra backslash, so it is not really
an improvement.

Unfortunately our documentation pages were written with AsciiDoc
7, and are not AsciiDoc 8 compatible.

With -aasciidoc7compatible, AsciiDoc 8 is _supposed_ to behave
compatibly, but in reality it does not format our documentation
correctly.  It certainly is possible that AsciiDoc 7 "happens to
work" with our documentation pages, and maybe the way we abuse
mark-ups can be argued the bug in _our_ documentation, but
nobody on our end worked on finding a satisfactory solution to
make our documentation format correctly with _both_ versions of
AsciiDoc yet.

I wrote about the differences between AsciiDoc 7, and AsciiDoc 8
with the "compatiblity" I found a few weeks ago on this list;
the most problematic was that 'asciidoc -aasciidoc7compatible'
loses carets in our description where they matter X-<.  The list
archive may know more about the details,

Re: [PATCH] Documentation typo.

[Pierre Habouzit]

[-- Attachment #1: Type: text/plain, Size: 2416 bytes --]

On Wed, Jun 06, 2007 at 02:16:36PM -0700, Junio C Hamano wrote:
> Pierre Habouzit <madcoder@debian.org> writes:
> 
> > From: Pierre Habouzit <pierre.habouzit@m4x.org>
> >
> > Signed-off-by: Pierre Habouzit <madcoder@debian.org>
> > ---
> >  Documentation/pull-fetch-param.txt |    2 +-
> >  1 files changed, 1 insertions(+), 1 deletions(-)
> >
> > diff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt
> > index 8d4e950..5bcdbc8 100644
> > --- a/Documentation/pull-fetch-param.txt
> > +++ b/Documentation/pull-fetch-param.txt
> > @@ -4,7 +4,7 @@
> >  
> >  <refspec>::
> >  	The canonical format of a <refspec> parameter is
> > -	`+?<src>:<dst>`; that is, an optional plus `+`, followed
> > +	`\+?<src>:<dst>`; that is, an optional plus `+`, followed
> >  	by the source ref, followed by a colon `:`, followed by
> >  	the destination ref.
> >  +
> 
> Not really.  I suspect you are using AsciiDoc 8?

  indeed ...

> Your patch does make AsciiDoc 8 keep '+' in the HTML output, but
> manual page output gets an extra backslash, so it is not really
> an improvement.

  Not for me, using asciidoc 8.2.1 on debian. It was because the manpage
was missing a '+' that I actually wrote this patch, as it was really
akward.

> Unfortunately our documentation pages were written with AsciiDoc
> 7, and are not AsciiDoc 8 compatible.
> 
> With -aasciidoc7compatible, AsciiDoc 8 is _supposed_ to behave
> compatibly, but in reality it does not format our documentation
> correctly.  It certainly is possible that AsciiDoc 7 "happens to
> work" with our documentation pages, and maybe the way we abuse
> mark-ups can be argued the bug in _our_ documentation, but
> nobody on our end worked on finding a satisfactory solution to
> make our documentation format correctly with _both_ versions of
> AsciiDoc yet.
> 
> I wrote about the differences between AsciiDoc 7, and AsciiDoc 8
> with the "compatiblity" I found a few weeks ago on this list;
> the most problematic was that 'asciidoc -aasciidoc7compatible'
> loses carets in our description where they matter X-<.  The list
> archive may know more about the details,

  Okay, I see, sorry for the noise then.

-- 
·O·  Pierre Habouzit
··O                                                madcoder@debian.org
OOO                                                http://www.madism.org

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: [PATCH] Documentation typo.

[Junio C Hamano]

Pierre Habouzit <madcoder@debian.org> writes:

>> Unfortunately our documentation pages were written with AsciiDoc
>> 7, and are not AsciiDoc 8 compatible.
>> 
>> With -aasciidoc7compatible, AsciiDoc 8 is _supposed_ to behave
>> compatibly, but in reality it does not format our documentation
>> correctly.  It certainly is possible that AsciiDoc 7 "happens to
>> work" with our documentation pages, and maybe the way we abuse
>> mark-ups can be argued the bug in _our_ documentation, but
>> nobody on our end worked on finding a satisfactory solution to
>> make our documentation format correctly with _both_ versions of
>> AsciiDoc yet.
>>  ...
>
>   Okay, I see, sorry for the noise then.

Well, it was NOT a noise.  Making the docs usable with both 7
and 8 is a task waiting for a volunteer ;-).

[RFT] Format our Documentation/ with both AsciiDoc 7 & 8

[Junio C Hamano]

It turns out that the attribute definition we have had for a
long time to hide "^" character from AsciiDoc 7 was not honored
by AsciiDoc 8 even under "-a asciidoc7compatible" mode.

Also the double colon at the end of definition list term needs
to be attached to the term, without a whitespace.  After this
minimum fixups, AsciiDoc 8 (I used 8.2.1 on Debian) with
compatibility mode seems to produce reasonably good results.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---

 * This is "Request for Test" to people who reported problems
   formatting our documentation with asciidoc 8.  To format with
   Asciidoc 8, you would need to say something like:

	$ make ASCIIDOC8=YesPlease doc

   I've compared the output generated with AsciiDoc 7.1.2
   without this patch, and generated with AscooDoc 7.1.2 and
   AsciiDoc 8.2.1 with this patch.  Aside from the expected
   obvious differences in:

   - embedded Git version string in manpage output
   - generation datestamp in HTML output
   - autogenerated anchor href="#id" and name="id" in HTML output

   the only differences I saw are:

   - _word_ is rendered in HTML as <em>word<em> in AsciiDoc 8,
     while it used to come out verbatim under AsciiDoc 7.  Nice.

   - HTML stylesheet is a bit different from AsciiDoc 8.
     Presumably an improvement.

 Documentation/Makefile                |    3 +++
 Documentation/asciidoc.conf           |    2 +-
 Documentation/git-cvsexportcommit.txt |    2 +-
 Makefile                              |    6 ++++++
 4 files changed, 11 insertions(+), 2 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 9cef480..4edf788 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -37,6 +37,9 @@ man7dir=$(mandir)/man7
 
 ASCIIDOC=asciidoc
 ASCIIDOC_EXTRA =
+ifdef ASCIIDOC8
+ASCIIDOC_EXTRA += -a asciidoc7compatible
+endif
 INSTALL?=install
 DOC_REF = origin/man
 
diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf
index 99302c5..c135b6e 100644
--- a/Documentation/asciidoc.conf
+++ b/Documentation/asciidoc.conf
@@ -8,7 +8,7 @@
 # the command.
 
 [attributes]
-caret=^
+caret=&#94;
 startsb=&#91;
 endsb=&#93;
 tilde=&#126;
diff --git a/Documentation/git-cvsexportcommit.txt b/Documentation/git-cvsexportcommit.txt
index 827711c..6c423e3 100644
--- a/Documentation/git-cvsexportcommit.txt
+++ b/Documentation/git-cvsexportcommit.txt
@@ -76,7 +76,7 @@ $ git-cvsexportcommit -v <commit-sha1>
 $ cvs commit -F .mgs <files>
 ------------
 
-Merge pending patches into CVS automatically -- only if you really know what you are doing ::
+Merge pending patches into CVS automatically -- only if you really know what you are doing::
 +
 ------------
 $ export GIT_DIR=~/project/.git
diff --git a/Makefile b/Makefile
index a70277b..d3b70d2 100644
--- a/Makefile
+++ b/Makefile
@@ -107,6 +107,8 @@ all::
 # Define USE_STDEV below if you want git to care about the underlying device
 # change being considered an inode change from the update-cache perspective.
 #
+# Define ASCIIDOC8 if you want to format documentation with AsciiDoc 8
+#
 # Define NO_PERL_MAKEMAKER if you cannot use Makefiles generated by perl's
 # MakeMaker (e.g. using ActiveState under Cygwin).
 #
@@ -684,6 +686,10 @@ ifndef V
 endif
 endif
 
+ifdef ASCIIDOC8
+	export ASCIIDOC8
+endif
+
 # Shell quote (do not use $(call) to accommodate ancient setups);
 
 SHA1_HEADER_SQ = $(subst ','\'',$(SHA1_HEADER))
-- 
1.5.2.1.280.g38570

Re: [RFT] Format our Documentation/ with both AsciiDoc 7 & 8

[Pierre Habouzit]

[-- Attachment #1: Type: text/plain, Size: 1355 bytes --]

On Thu, Jun 14, 2007 at 11:34:20PM -0700, Junio C Hamano wrote:
> It turns out that the attribute definition we have had for a
> long time to hide "^" character from AsciiDoc 7 was not honored
> by AsciiDoc 8 even under "-a asciidoc7compatible" mode.
> 
> Also the double colon at the end of definition list term needs
> to be attached to the term, without a whitespace.  After this
> minimum fixups, AsciiDoc 8 (I used 8.2.1 on Debian) with
> compatibility mode seems to produce reasonably good results.
> 
> Signed-off-by: Junio C Hamano <gitster@pobox.com>
> ---
> 
>  * This is "Request for Test" to people who reported problems
>    formatting our documentation with asciidoc 8.  To format with
>    Asciidoc 8, you would need to say something like:
> 
> 	$ make ASCIIDOC8=YesPlease doc

  sadly, it does not fixes the issue I reported with git-pull.1 (e.g.)
that reads:

   <refspec>
       The canonical format of a <refspec> parameter is ?<src>:<dst>; that

whereas it should be:

   <refspec>
       The canonical format of a <refspec> parameter is +?<src>:<dst>; that


But I've not seen any serious or even noticeable regression here.
-- 
·O·  Pierre Habouzit
··O                                                madcoder@debian.org
OOO                                                http://www.madism.org

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: [RFT] Format our Documentation/ with both AsciiDoc 7 & 8

[Junio C Hamano]

Pierre Habouzit <madcoder@debian.org> writes:

>   sadly, it does not fixes the issue I reported with git-pull.1 (e.g.)
> that reads:
>
>    <refspec>
>        The canonical format of a <refspec> parameter is ?<src>:<dst>; that
>
> whereas it should be:
>
>    <refspec>
>        The canonical format of a <refspec> parameter is +?<src>:<dst>; that

That is very unexpected, especially as your e-mail address is in
debian.org.

 * My local test and build usually is done with AsciiDoc 7.1.2
   that is shipped with Debian, without any local modifications.
   The part you quoted is formatted like this (I indented for
   e-mail inclusion and line-wrapped below):

    .PP
    <refspec>
    .RS 3n

    The canonical format of a <refspec> parameter is +?<src>:<dst>;
    that is, an optional plus +, followed by the source ref,
    followed by a colon :, followed by the destination ref.

   This is the same with or without the patch we are
   discussing.

 * I updated my notebook that runs Debian with AsciiDoc 8.2.1
   and tested with the patch.  The formatted result matches the
   above.

 * I tried the above with a hand-installed AsciiDoc 8.2.1 from
   the tarball distribution.  Again, the formatted result of the
   quoted part matches.

 * The preformatted manual pages on man branch in git.git are
   generated on a k.org machine that runs AsciiDoc 7.0.2 on
   FC5.  The version before the patch is formatted like this:

    .TP
    <refspec>
    The canonical format of a <refspec> parameter is +?<src>:<dst>;
    that is, an optional plus +, followed by the source ref,
    followed by a colon :, followed by the destination ref.

   I haven't had a chance to test how it comes out with the
   patch, but because the only difference under AsciiDoc 7 is
   the definition of {caret} macro, I do not expect any change
   in the quoted area.

In other words, there is no breakage like you are observing in
the original (nor updated) version with any of the platforms and
AsciiDoc versions I had handy to test.  There is something
different with the version of AsciiDoc you are using, but I
cannot tell what that is.

Re: [RFT] Format our Documentation/ with both AsciiDoc 7 & 8

[Pierre Habouzit]

[-- Attachment #1: Type: text/plain, Size: 1097 bytes --]

On Fri, Jun 15, 2007 at 03:52:09PM -0700, Junio C Hamano wrote:
> Pierre Habouzit <madcoder@debian.org> writes:
> 
> >   sadly, it does not fixes the issue I reported with git-pull.1 (e.g.)
> > that reads:
> >
> >    <refspec>
> >        The canonical format of a <refspec> parameter is ?<src>:<dst>; that
> >
> > whereas it should be:
> >
> >    <refspec>
> >        The canonical format of a <refspec> parameter is +?<src>:<dst>; that
> 
> That is very unexpected, especially as your e-mail address is in
> debian.org.

  Well I'm running unstable, with asciidoc 8.2.1.

>  * I updated my notebook that runs Debian with AsciiDoc 8.2.1
>    and tested with the patch.  The formatted result matches the
>    above.

  AAAAND I'M AN IDIOT. I tested it in the wrong branch, without the
patch. do'h.

  I confirm that it works perfectly. Now, does someone knows a hole
where I can hide into ?

-- 
·O·  Pierre Habouzit
··O                                                madcoder@debian.org
OOO                                                http://www.madism.org

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: [RFT] Format our Documentation/ with both AsciiDoc 7 & 8

[Junio C Hamano]

Pierre Habouzit <madcoder@debian.org> writes:

>   AAAAND I'M AN IDIOT. I tested it in the wrong branch, without the
> patch. do'h.
>
>   I confirm that it works perfectly. Now, does someone knows a hole
> where I can hide into ?

You don't need a hole.  Thanks for a timely confirmation.

[PATCH] documentation typo

[Diego Calleja]

According to a bug reported in bugzilla...

--- 2.6/Documentation/ide.txt.wrong	2006-01-05 13:16:06.000000000 +0100
+++ 2.6/Documentation/ide.txt	2006-01-05 13:16:10.000000000 +0100
@@ -244,7 +244,7 @@ Summary of ide driver parameters for ker
 
  "hdx=bswap"		: same as above..........
 
- "hdx=scsi"		: the return of the ide-scsi flag, this is useful for
+ "hdx=ide-scsi"		: the return of the ide-scsi flag, this is useful for
  			  allowing ide-floppy, ide-tape, and ide-cdrom|writers
  			  to use ide-scsi emulation on a device specific option.
 

Re: [PATCH] documentation typo

[Bartlomiej Zolnierkiewicz]

Hi,

On 1/5/06, Diego Calleja <diegocg@gmail.com> wrote:
> According to a bug reported in bugzilla...
>
> --- 2.6/Documentation/ide.txt.wrong     2006-01-05 13:16:06.000000000 +0100
> +++ 2.6/Documentation/ide.txt   2006-01-05 13:16:10.000000000 +0100
> @@ -244,7 +244,7 @@ Summary of ide driver parameters for ker
>
>   "hdx=bswap"           : same as above..........
>
> - "hdx=scsi"            : the return of the ide-scsi flag, this is useful for
> + "hdx=ide-scsi"                : the return of the ide-scsi flag, this is useful for
>                           allowing ide-floppy, ide-tape, and ide-cdrom|writers
>                           to use ide-scsi emulation on a device specific option.

This is not quite correct: ide-scsi is a separate device driver and
"hdx=ide-scsi" tells IDE core to try this driver first for device
"hdx" (OTOH "ide=scsi" tells other device drivers to not bind to
device "hdx").  Both options are confusing and IDE specific.

In recent kernels you can use generic sysfs interface to
bind/unbind device to drivers _dynamically_ without using
"hdx=scsi" and "hdx=ide-scsi" et all (these option can die):

[root@trik /]# cd /sys/bus/ide/drivers/
[root@trik drivers]# ls
ide-cdrom  ide-disk  ide-scsi
[root@trik drivers]# ls ide-cdrom ide-scsi
ide-cdrom:
1.0  bind  module  unbind

ide-scsi:
bind  module  unbind
[root@trik drivers]# echo -n "1.0">ide-cdrom/unbind
[root@trik drivers]# ls ide-cdrom ide-scsi
ide-cdrom:
bind  module  unbind

ide-scsi:
bind  module  unbind
[root@trik drivers]# echo -n "1.0">ide-scsi/bind
[root@trik drivers]# ls ide-cdrom ide-scsi
ide-cdrom:
bind  module  unbind

ide-scsi:
1.0  bind  module  unbind

I would greatly appreciate if you update ide.txt accordingly.

Thanks,
Bartlomiej

Re: [PATCH] documentation typo

[Diego Calleja]

El Thu, 5 Jan 2006 15:43:53 +0100,
Bartlomiej Zolnierkiewicz <bzolnier@gmail.com> escribió:

> I would greatly appreciate if you update ide.txt accordingly.


If this doesn't look OK (it's crappy to paste command examples
instead of explaining the interface) I'll rewrite it after the
weekend.

--- test/Documentation/ide.txt.old	2006-01-13 16:58:28.000000000 +0100
+++ test/Documentation/ide.txt	2006-01-13 17:08:08.000000000 +0100
@@ -244,10 +244,44 @@ Summary of ide driver parameters for ker
 
  "hdx=bswap"		: same as above..........
 
- "hdx=scsi"		: the return of the ide-scsi flag, this is useful for
+ "hdx=ide-scsi" (*)	: the return of the ide-scsi flag, this is useful for
  			  allowing ide-floppy, ide-tape, and ide-cdrom|writers
  			  to use ide-scsi emulation on a device specific option.
 
+ "hdx=scsi" (*)	: This option tells IDE drivers not to bind to device
+			  "hdx"
+
+ [(*) Notice that in current kernels you can use the generic sysfs interface
+  to bind/unbind devices to drivers dynamically without using "hdx=scsi"
+  and/or "hdx=ide-scsi", so those boot options may be deprecated in the future,
+  ej:
+
+   [root@trik /]# cd /sys/bus/ide/drivers/
+   [root@trik drivers]# ls
+   ide-cdrom  ide-disk  ide-scsi
+   [root@trik drivers]# ls ide-cdrom ide-scsi
+   ide-cdrom:
+   1.0  bind  module  unbind
+   
+   ide-scsi:
+   bind  module  unbind
+   [root@trik drivers]# echo -n "1.0">ide-cdrom/unbind
+   [root@trik drivers]# ls ide-cdrom ide-scsi
+   ide-cdrom:
+   bind  module  unbind
+   
+   ide-scsi:
+   bind  module  unbind
+   [root@trik drivers]# echo -n "1.0">ide-scsi/bind
+   [root@trik drivers]# ls ide-cdrom ide-scsi
+   ide-cdrom:
+   bind  module  unbind
+   
+   ide-scsi:
+   1.0  bind  module  unbind
+   [root@trik drivers]#
+   
+
  "idebus=xx"		: inform IDE driver of VESA/PCI bus speed in MHz,
 			  where "xx" is between 20 and 66 inclusive,
 			  used when tuning chipset PIO modes.

Re: [PATCH] documentation typo

[Bartlomiej Zolnierkiewicz]

On 1/13/06, Diego Calleja <diegocg@gmail.com> wrote:
> El Thu, 5 Jan 2006 15:43:53 +0100,
> Bartlomiej Zolnierkiewicz <bzolnier@gmail.com> escribió:
>
> > I would greatly appreciate if you update ide.txt accordingly.
>
>
> If this doesn't look OK (it's crappy to paste command examples
> instead of explaining the interface) I'll rewrite it after the
> weekend.

Well, examples are fine but some explanation would be needed.
I'll wait for revised version (please also add that you need
CONFIG_HOTPLUG=y for using sysfs interface - this is due
one of the recent changes in the kernel driver core).

Thanks,
Bartlomiej

> --- test/Documentation/ide.txt.old      2006-01-13 16:58:28.000000000 +0100
> +++ test/Documentation/ide.txt  2006-01-13 17:08:08.000000000 +0100
> @@ -244,10 +244,44 @@ Summary of ide driver parameters for ker
>
>   "hdx=bswap"           : same as above..........
>
> - "hdx=scsi"            : the return of the ide-scsi flag, this is useful for
> + "hdx=ide-scsi" (*)    : the return of the ide-scsi flag, this is useful for
>                           allowing ide-floppy, ide-tape, and ide-cdrom|writers
>                           to use ide-scsi emulation on a device specific option.
>
> + "hdx=scsi" (*)        : This option tells IDE drivers not to bind to device
> +                         "hdx"
> +
> + [(*) Notice that in current kernels you can use the generic sysfs interface
> +  to bind/unbind devices to drivers dynamically without using "hdx=scsi"
> +  and/or "hdx=ide-scsi", so those boot options may be deprecated in the future,
> +  ej:
> +
> +   [root@trik /]# cd /sys/bus/ide/drivers/
> +   [root@trik drivers]# ls
> +   ide-cdrom  ide-disk  ide-scsi
> +   [root@trik drivers]# ls ide-cdrom ide-scsi
> +   ide-cdrom:
> +   1.0  bind  module  unbind
> +
> +   ide-scsi:
> +   bind  module  unbind
> +   [root@trik drivers]# echo -n "1.0">ide-cdrom/unbind
> +   [root@trik drivers]# ls ide-cdrom ide-scsi
> +   ide-cdrom:
> +   bind  module  unbind
> +
> +   ide-scsi:
> +   bind  module  unbind
> +   [root@trik drivers]# echo -n "1.0">ide-scsi/bind
> +   [root@trik drivers]# ls ide-cdrom ide-scsi
> +   ide-cdrom:
> +   bind  module  unbind
> +
> +   ide-scsi:
> +   1.0  bind  module  unbind
> +   [root@trik drivers]#
> +
> +
>   "idebus=xx"           : inform IDE driver of VESA/PCI bus speed in MHz,
>                           where "xx" is between 20 and 66 inclusive,
>                           used when tuning chipset PIO modes.
>

Re: [PATCH] documentation typo

[Diego Calleja]

El Fri, 13 Jan 2006 17:17:33 +0100,
Bartlomiej Zolnierkiewicz <bzolnier@gmail.com> escribió:

> Well, examples are fine but some explanation would be needed.
> I'll wait for revised version (please also add that you need
> CONFIG_HOTPLUG=y for using sysfs interface - this is due
> one of the recent changes in the kernel driver core).

Of, this is not 100% perfect but it's much better:

- I added a CONFIG_HOTPLUG dependeny for ide-scsi. If the sysfs interface
  is the Right Way of doing it and the boot parameters are going to be
  removed some day, it has sense no?

- I "deprecated" the boot parameters by adding a printk and a entry to
  feature-removal-schedule.txt. I don't know if this is what you want
  but I though it was the right thing

Index: test/Documentation/ide.txt
===================================================================
--- test.orig/Documentation/ide.txt	2006-01-13 16:58:28.000000000 +0100
+++ test/Documentation/ide.txt	2006-01-15 23:08:34.000000000 +0100
@@ -244,9 +244,15 @@
 
  "hdx=bswap"		: same as above..........
 
- "hdx=scsi"		: the return of the ide-scsi flag, this is useful for
+ "hdx=ide-scsi"		: the return of the ide-scsi flag, this is useful for
  			  allowing ide-floppy, ide-tape, and ide-cdrom|writers
  			  to use ide-scsi emulation on a device specific option.
+			  NOTE: This boot option is deprecated (*) and may be
+			  removed in the future
+
+ "hdx=scsi"		: This option tells IDE drivers not to bind to device
+			  "hdx". NOTE: This boot option is deprecated (*) and
+			  may be removed in the future.
 
  "idebus=xx"		: inform IDE driver of VESA/PCI bus speed in MHz,
 			  where "xx" is between 20 and 66 inclusive,
@@ -317,8 +323,44 @@
 
 Everything else is rejected with a "BAD OPTION" message.
 
+
+(*): hdx=ide-scsi and hdx=scsi boot options: These two boot options have been
+deprecated by a new sysfs interface, which allows to bind/unbind devices to
+drivers dinamically. Notice that you need to enable CONFIG_HOTPLUG (Hotplug
+support) to use this:
+
+For every IDE bus in the system, there's a /sys/devices/$PCIBUS/$PCIID/idex/
+subdirectory (where $PCIBUS is the identifier of the PCI bus, something like
+"pci0000:00", and $PCIID is the PCI ID of the ide bus device - the same you get
+when you run lspci - something like "0000:00:0f.1". idex is ide0, ide1, etc)
+
+In each one of those subdirectories, there's another subdirectory with a name
+like "0.0", "1.0", etc: The first number identifies the IDE bus (ide0, ide1
+etc) and the second one the device connected at that bus. That subdirectory
+has some information about your device and more subdirectories pointing to
+other places in the sysfs tree where you can find information related with
+that device. You can also get those names by running "systool -b ide".
+
+The ide-disk, ide-cdrom and ide-scsi drivers also have their own sysfs
+subdirectory at /sys/bus/ide/drivers/ide-disk/, /sys/bus/ide/drivers/ide-scsi/,
+etc. In each one of those subdirectories there's a bind and a unbind file. The
+way to bind/unbind a device to a driver dinamically is to write the "name"
+of those files; ej: echo "1.0" > /sys/bus/ide/drivers/ide-scsi/bind to bind
+the device 1.0 to the ide-scsi driver. A symlink named "1.0" will appear in the
+ide-scsi/ directory pointing to the /sys/devices/$PCIBUS/$PCIID/ide1/1.0/
+directory. In that directory, you'll also "driver" symlink pointing back
+to the ide-scsi subdirectory. Alternatively, you can see the current state
+of all the ide interfaces by running "systools -b ide -D"
+
+While this is more complex than adding a boot parameter, this allows to
+change the device/driver bindings dynamically so no static boot parameters
+are needed (which is useful for distros so they can run in different
+hardware configurations where devices are detected dinamically and
+binded/unbinded to different interfaces dinamically)
+
 ================================================================================
 
+
 IDE ATAPI streaming tape driver
 -------------------------------
 
Index: test/drivers/ide/ide.c
===================================================================
--- test.orig/drivers/ide/ide.c	2006-01-13 02:40:44.000000000 +0100
+++ test/drivers/ide/ide.c	2006-01-15 22:00:14.000000000 +0100
@@ -1554,6 +1554,9 @@
 		hwif = &ide_hwifs[hw];
 		drive = &hwif->drives[unit];
 		if (strncmp(s + 4, "ide-", 4) == 0) {
+			printk("hd%c: \"hdx=ide-scsi\" boot parameter has been
+			    obsoleted by a better mechanism and may be removed
+			    in the future, check Documentation/ide.txt\n", unit);
 			strlcpy(drive->driver_req, s + 4, sizeof(drive->driver_req));
 			goto done;
 		}
@@ -1593,6 +1596,10 @@
 				drive->sect0 = 63;
 				goto done;
 			case -14: /* "scsi" */
+				printk("hd%c: \"hdx=scsi\" boot parameter has
+				    been obsoleted by a better mechanism and may
+				    be removed in the future, check
+				    Documentation/ide.txt\n", unit);
 				drive->scsi = 1;
 				goto done;
 			case 3: /* cyl,head,sect */
Index: test/Documentation/feature-removal-schedule.txt
===================================================================
--- test.orig/Documentation/feature-removal-schedule.txt	2006-01-13 02:40:41.000000000 +0100
+++ test/Documentation/feature-removal-schedule.txt	2006-01-15 22:07:28.000000000 +0100
@@ -139,3 +139,12 @@
 	brother on Alchemy SOCs.  The loss of features is not considered an
 	issue.
 Who:	Ralf Baechle <ralf@linux-mips.org>
+
+---------------------------
+
+What:	hdx=ide-scsi/hdx=scsi boot parameters
+When:	June 2006
+Why:	In current kernels there's a sysfs interface to bind/unbind devices
+	to drivers dynamically which replaces those parameters, see
+	Documentation/ide.txt
+Who:	Bartlomiej Zolnierkiewicz <B.Zolnierkiewicz@elka.pw.edu.pl>
Index: test/drivers/ide/Kconfig
===================================================================
--- test.orig/drivers/ide/Kconfig	2006-01-13 02:40:44.000000000 +0100
+++ test/drivers/ide/Kconfig	2006-01-15 23:13:41.000000000 +0100
@@ -234,7 +234,7 @@
 
 config BLK_DEV_IDESCSI
 	tristate "SCSI emulation support"
-	depends on SCSI
+	depends on SCSI && HOTPLUG
 	---help---
 	  WARNING: ide-scsi is no longer needed for cd writing applications!
 	  The 2.6 kernel supports direct writing to ide-cd, which eliminates
@@ -249,12 +249,10 @@
 	  driver has been written (for example, an ATAPI PD-CD drive);
 	  you can then use this emulation together with an appropriate SCSI
 	  device driver. In order to do this, say Y here and to "SCSI support"
-	  and "SCSI generic support", below. You must then provide the kernel
-	  command line "hdx=ide-scsi" (try "man bootparam" or see the
-	  documentation of your boot loader (lilo or loadlin) about how to
-	  pass options to the kernel at boot time) for devices if you want the
-	  native EIDE sub-drivers to skip over the native support, so that
-	  this SCSI emulation can be used instead.
+	  and "SCSI generic support", below. To force a device to use this
+	  SCSI emulation interface you can use sysfs to do it at runtime as
+	  explained in <file:Documentation/ide.txt> (notice that this needs
+	  CONFIG_HOTPLUG)
 
 	  Note that this option does NOT allow you to attach SCSI devices to a
 	  box that doesn't have a SCSI host adapter installed.

Re: [PATCH] documentation typo

[Diego Calleja]

El Sun, 15 Jan 2006 23:24:03 +0100,
Diego Calleja <diegocg@gmail.com> escribió:


Did you like the patch? I can remove everything but the documentation
if you want

Re: [PATCH] documentation typo

[Bartlomiej Zolnierkiewicz]

Hi,

On 1/15/06, Diego Calleja <diegocg@gmail.com> wrote:
> El Fri, 13 Jan 2006 17:17:33 +0100,
> Bartlomiej Zolnierkiewicz <bzolnier@gmail.com> escribió:
>
> > Well, examples are fine but some explanation would be needed.
> > I'll wait for revised version (please also add that you need
> > CONFIG_HOTPLUG=y for using sysfs interface - this is due
> > one of the recent changes in the kernel driver core).
>
> Of, this is not 100% perfect but it's much better:
>
> - I added a CONFIG_HOTPLUG dependeny for ide-scsi. If the sysfs interface
>   is the Right Way of doing it and the boot parameters are going to be
>   removed some day, it has sense no?

Hmm, ide-scsi works just fine without CONFIG_HOTPLUG.

IMO "select CONFIG_HOTPLUG" is better but I think that we can
drop CONFIG_HOTPLUG dependency entirely and see if anybody
complains during transition period (unlikely).

> - I "deprecated" the boot parameters by adding a printk and a entry to
>   feature-removal-schedule.txt. I don't know if this is what you want
>   but I though it was the right thing

Cool.

> --- test.orig/drivers/ide/ide.c 2006-01-13 02:40:44.000000000 +0100
> +++ test/drivers/ide/ide.c      2006-01-15 22:00:14.000000000 +0100
> @@ -1554,6 +1554,9 @@
>                 hwif = &ide_hwifs[hw];
>                 drive = &hwif->drives[unit];
>                 if (strncmp(s + 4, "ide-", 4) == 0) {
> +                       printk("hd%c: \"hdx=ide-scsi\" boot parameter has been
> +                           obsoleted by a better mechanism and may be removed
> +                           in the future, check Documentation/ide.txt\n", unit);

please add KERN_WARNING

>                         strlcpy(drive->driver_req, s + 4, sizeof(drive->driver_req));
>                         goto done;
>                 }
> @@ -1593,6 +1596,10 @@
>                                 drive->sect0 = 63;
>                                 goto done;
>                         case -14: /* "scsi" */
> +                               printk("hd%c: \"hdx=scsi\" boot parameter has
> +                                   been obsoleted by a better mechanism and may
> +                                   be removed in the future, check
> +                                   Documentation/ide.txt\n", unit);

ditto

Rest of the patch is perfectly fine.

Thanks and sorry for the delay,
Bartlomiej

Re: [PATCH] documentation typo

[Diego Calleja]

El Fri, 27 Jan 2006 01:36:09 +0100,
Bartlomiej Zolnierkiewicz <bzolnier@gmail.com> escribió:

> IMO "select CONFIG_HOTPLUG" is better but I think that we can
> drop CONFIG_HOTPLUG dependency entirely and see if anybody
> complains during transition period (unlikely).

OK, removed

> please add KERN_WARNING

done


Signed-off-by: Diego Calleja <diegocg@gmail.com>

Index: test/Documentation/feature-removal-schedule.txt
===================================================================
--- test.orig/Documentation/feature-removal-schedule.txt	2006-01-16 01:46:27.000000000 +0100
+++ test/Documentation/feature-removal-schedule.txt	2006-01-27 02:37:44.000000000 +0100
@@ -148,3 +148,12 @@
 	brother on Alchemy SOCs.  The loss of features is not considered an
 	issue.
 Who:	Ralf Baechle <ralf@linux-mips.org>
+
+---------------------------
+
+What:	hdx=ide-scsi and hdx=scsi boot parameters
+When:	June 2006
+Why:	In current kernels there's a sysfs interface to bind/unbind devices
+	to drivers dynamically which replaces those parameters, see
+	Documentation/ide.txt
+Who:	Bartlomiej Zolnierkiewicz <B.Zolnierkiewicz@elka.pw.edu.pl>
Index: test/Documentation/ide.txt
===================================================================
--- test.orig/Documentation/ide.txt	2006-01-13 02:40:41.000000000 +0100
+++ test/Documentation/ide.txt	2006-01-27 02:49:50.000000000 +0100
@@ -247,6 +247,12 @@
  "hdx=scsi"		: the return of the ide-scsi flag, this is useful for
  			  allowing ide-floppy, ide-tape, and ide-cdrom|writers
  			  to use ide-scsi emulation on a device specific option.
+			  NOTE: This boot option is deprecated (*) and will be
+			  removed in the future.
+
+ "hdx=scsi"		: This option tells IDE drivers not to bind to device
+			  "hdx". NOTE: This boot option is deprecated (*) and
+			  will be removed in the future.
 
  "idebus=xx"		: inform IDE driver of VESA/PCI bus speed in MHz,
 			  where "xx" is between 20 and 66 inclusive,
@@ -317,6 +323,41 @@
 
 Everything else is rejected with a "BAD OPTION" message.
 
+
+(*): hdx=ide-scsi and hdx=scsi boot options: These two boot options have been
+deprecated by a new sysfs interface, which allows to bind/unbind devices to
+drivers dinamically. Notice that you need to enable CONFIG_HOTPLUG (Hotplug
+support) to use this:
+
+For every IDE bus in the system, there's a /sys/devices/$PCIBUS/$PCIID/idex/
+subdirectory (where $PCIBUS is the identifier of the PCI bus, something like
+"pci0000:00", and $PCIID is the PCI ID of the ide bus device - the same you get
+when you run lspci, something like "0000:00:0f.1". idex is ide0, ide1, etc)
+
+In each one of those subdirectories, there's another subdirectory with a name
+like "0.0", "1.0", etc: The first number identifies the IDE bus (ide0, ide1
+etc) and the second one the device connected at that bus. That subdirectory
+has some information about your device and more subdirectories pointing to
+other places in the sysfs tree where you can find information related with
+that device. You can also get those names by running "systool -b ide".
+
+The ide-disk, ide-cdrom and ide-scsi drivers also have their own sysfs
+subdirectory at /sys/bus/ide/drivers/ide-disk/, /sys/bus/ide/drivers/ide-scsi/,
+etc. In each one of those subdirectories there's a bind and a unbind file. The
+way to bind/unbind a device to a driver dinamically is to write the "name" of
+the IDE device in those files; ej: echo "1.0" > /sys/bus/ide/drivers/ide-scsi/bind
+to bind the device 1.0 to the ide-scsi driver. A symlink named "1.0" will appear
+in the ide-scsi/ directory pointing to the /sys/devices/$PCIBUS/$PCIID/ide1/1.0/
+directory. In that directory, you'll also "driver" symlink pointing back
+to the ide-scsi subdirectory. Alternatively, you can see the current state
+of all the ide interfaces by running "systools -b ide -D"
+
+While this is more complex than adding a boot parameter, this allows to
+change the device/driver bindings dynamically so no static boot parameters
+are needed (which is useful for distros so they can run in different
+hardware configurations where devices can be detected dinamically and need to
+be configured dinamically)
+
 ================================================================================
 
 IDE ATAPI streaming tape driver
Index: test/drivers/ide/Kconfig
===================================================================
--- test.orig/drivers/ide/Kconfig	2006-01-13 02:40:44.000000000 +0100
+++ test/drivers/ide/Kconfig	2006-01-27 02:53:10.000000000 +0100
@@ -249,12 +249,10 @@
 	  driver has been written (for example, an ATAPI PD-CD drive);
 	  you can then use this emulation together with an appropriate SCSI
 	  device driver. In order to do this, say Y here and to "SCSI support"
-	  and "SCSI generic support", below. You must then provide the kernel
-	  command line "hdx=ide-scsi" (try "man bootparam" or see the
-	  documentation of your boot loader (lilo or loadlin) about how to
-	  pass options to the kernel at boot time) for devices if you want the
-	  native EIDE sub-drivers to skip over the native support, so that
-	  this SCSI emulation can be used instead.
+	  and "SCSI generic support", below. To force a device to use this
+	  SCSI emulation interface you can use sysfs to do it at runtime as
+	  explained in <file:Documentation/ide.txt> (notice that this interface
+	  needs CONFIG_HOTPLUG)
 
 	  Note that this option does NOT allow you to attach SCSI devices to a
 	  box that doesn't have a SCSI host adapter installed.
Index: test/drivers/ide/ide.c
===================================================================
--- test.orig/drivers/ide/ide.c	2006-01-16 01:46:28.000000000 +0100
+++ test/drivers/ide/ide.c	2006-01-27 02:43:18.000000000 +0100
@@ -1554,6 +1554,10 @@
 		hwif = &ide_hwifs[hw];
 		drive = &hwif->drives[unit];
 		if (strncmp(s + 4, "ide-", 4) == 0) {
+			printk(KERN_WARNING "hd%c: \"hdx=ide-scsi\" boot
+			    parameter has been obsoleted by a better mechanism
+			    and will be removed in the future, read
+			    Documentation/ide.txt\n", unit);
 			strlcpy(drive->driver_req, s + 4, sizeof(drive->driver_req));
 			goto done;
 		}
@@ -1593,6 +1597,10 @@
 				drive->sect0 = 63;
 				goto done;
 			case -14: /* "scsi" */
+				printk(KERN_WARNING "hd%c: \"hdx=scsi\" boot
+				    parameter has been obsoleted by a better
+				    mechanism and may be removed in the future,
+				    read Documentation/ide.txt\n", unit);
 				drive->scsi = 1;
 				goto done;
 			case 3: /* cyl,head,sect */