Re: [RFC PATCH v2 15/20] iommu/amd: AMD IOMMU support for memory encryption

[Borislav Petkov]

On Thu, Sep 15, 2016 at 11:57:41AM -0500, Tom Lendacky wrote:
> If I do that, then I could put an #ifdef in the header to include the
> asm/mem_encrypt.h if the memory encryption is configured, else set the
> value to zero.

Yeah, something along those lines...

> I'll look into this. One immediate question becomes do we keep the
> name very specific vs. making it more generic, sme_me_mask vs me_mask,
> etc.

No strong opinion either way from me. My angle is that whatever it is,
we can always rename it later if we decide to.

-- 
Regards/Gruss,
Boris.

ECO tip #101: Trim your mails when you reply.
--
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC PATCH v2 19/20] x86: Access the setup data through debugfs un-encrypted

[Borislav Petkov]

On Thu, Sep 15, 2016 at 12:08:04PM -0500, Tom Lendacky wrote:
> The problem is that this physical address does not contain the
> encryption bit, and even if it did, it wouldn't matter.  The __va()
> define creates a virtual address that will be mapped as encrypted given
> the current approach (which is how I found this).  It's only ioremap()
> that would create a mapping without the encryption attribute and since
> this is unencrypted data it needs to be access accordingly.

I see. So since this is not obvious, please add this explanation to maybe

Documentation/x86/amd-memory-encryption.txt

and point in there to an example or so so.

Thanks.

-- 
Regards/Gruss,
Boris.

ECO tip #101: Trim your mails when you reply.
--
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 07/17] SubmitChecklist: rename to RST and add to the development-proccess book

[Jean Delvare]

On Wed, 14 Sep 2016 20:05:52 -0300, Mauro Carvalho Chehab wrote:
> Add it to the development-process book, by renaming it to
> SubmitChecklist.rst and move it to the development-process
> directory.
> 
> Signed-off-by: Mauro Carvalho Chehab 
> ---
>  .../{SubmitChecklist => development-process/SubmitChecklist.rst}  | 2 +-
>  Documentation/development-process/index.rst   | 1 +
>  Documentation/hwmon/submitting-patches| 2 +-
>  Documentation/ja_JP/SubmitChecklist   | 4 
> ++--
>  Documentation/ja_JP/SubmittingPatches | 2 +-
>  Documentation/zh_CN/SubmittingPatches | 2 +-
>  6 files changed, 7 insertions(+), 6 deletions(-)
>  rename Documentation/{SubmitChecklist => 
> development-process/SubmitChecklist.rst} (98%)
> (...)

For the hwmon part:

Reviewed-by: Jean Delvare 

-- 
Jean Delvare
SUSE L3 Support
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH V6] usb: core: Introduce a USB port LED trigger

[Rafał Miłecki]

From: Rafał Miłecki 

This commit adds a new trigger responsible for turning on LED when USB
device gets connected to the selected USB port. This can can useful for
various home routers that have USB port(s) and a proper LED telling user
a device is connected.

The trigger gets its documentation file but basically it just requires
enabling it and selecting USB ports (e.g. echo 1 > ports/usb1-1).

There was a long discussion on design of this driver. Its current state
is a result of picking them most adjustable solution as others couldn't
handle all cases.

1) It wasn't possible for the driver to register separated trigger for
   each USB port. Some physical USB ports are handled by more than one
   controller and so by more than one USB port. E.g. USB 2.0 physical
   port may be handled by OHCI's port and EHCI's port.
   It's also not possible to assign more than 1 trigger to a single LED
   and implementing such feature would be tricky due to syncing triggers
   and sysfs conflicts with old triggers.

2) Another idea was to register trigger per USB hub. This wouldn't allow
   handling devices with multiple USB LEDs and controllers (hubs)
   controlling more than 1 physical port. It's common for hubs to have
   few ports and each may have its own LED.

This final trigger is highly flexible. It allows selecting any USB ports
for any LED. It was also modified (comparing to the initial version) to
allow choosing ports rather than having user /guess/ proper names. It
was successfully tested on SmartRG SR400ac which has 3 USB LEDs,
2 physical ports and 3 controllers.

It was noted USB subsystem already has usb-gadget and usb-host triggers
but they are pretty trivial ones. They indicate activity only and can't
have ports specified.

In future it may be good idea to consider adding activity support to
usbport as well. This should allow switching to this more generic driver
and maybe marking old ones as obsolete.
This can be implemented with another sysfs file for setting mode. The
default mode wouldn't change so there won't be ABI breakage and so such
feature can be safely implemented later.

There was also an idea of supporting other devices (PCI, SDIO, etc.) but
as this driver already contains some USB specific code (and will get
more) these should be probably separated drivers (triggers).

Signed-off-by: Rafał Miłecki 
---
V2: Trying to add DT support, idea postponed as it will take more time
to discuss the bindings.
V3: Fix typos in commit and Documentation (thanks Jacek!)
Use "ports" sysfs file for adding and removing USB ports (thx Jacek)
Check if there is USB device connected after adding new USB port
Fix memory leak or two
V3.5: Fix e-mail address (thanks Matthias)
  Simplify conditions in usbport_trig_notify (thx Matthias)
  Make "ports" a subdirectory with file per port, to match one value
  per file sysfs rule (thanks Greg)
  As "ports" couldn't be used for adding and removing ports anymore,
  there are now "new_port" and "remove_port". Having them makes this
  API also common with e.g. pci and usb buses.
V4: Add Documentation/ABI/testing/sysfs-class-led-trigger-usbport and
reference it in Documentation/leds/ledtrig-usbport.txt to avoid doc
duplication.
V5: Update commit message to explain driver design & Documentation
Avoid specifying ports manually and dummy files (chmod )
Don't use kobject_create_and_add but a struct attribute_group
Fix typo, improve comments, update Date
V6: Move code to USB subsystem (thx Peter and Pavel)
Rebase on top of usb-next branch
Describe relation to existing USB triggers in commit message
Switch to GPL v2 (I just prefer it after reading Linus's arguments)

Can someone from LED subsystem (Jacek? Richard?) give an Ack, if this
patch looks OK to you, please? I hope it could help Greg taking it into
usb-next.
---
 .../ABI/testing/sysfs-class-led-trigger-usbport|  12 +
 Documentation/leds/ledtrig-usbport.txt |  41 +++
 drivers/usb/core/Kconfig   |   8 +
 drivers/usb/core/Makefile  |   2 +
 drivers/usb/core/ledtrig-usbport.c | 314 +
 5 files changed, 377 insertions(+)
 create mode 100644 Documentation/ABI/testing/sysfs-class-led-trigger-usbport
 create mode 100644 Documentation/leds/ledtrig-usbport.txt
 create mode 100644 drivers/usb/core/ledtrig-usbport.c

diff --git a/Documentation/ABI/testing/sysfs-class-led-trigger-usbport 
b/Documentation/ABI/testing/sysfs-class-led-trigger-usbport
new file mode 100644
index 000..f440e69
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-led-trigger-usbport
@@ -0,0 +1,12 @@
+What:  /sys/class/leds//ports/
+Date:  September 2016
+KernelVersion: 4.9
+Contact:   linux-l...@vger.kernel.org
+   linux-...@vger.kernel.org
+Description:
+   Every dir entry represents a single USB port that can be
+   selected

Re: [PATCH] DMA-API-HOWTO: is no more

[Jonathan Corbet]

On Sun, 11 Sep 2016 15:58:53 +0200
Christoph Hellwig  wrote:

> So don't mention it.

Applied to the docs tree, thanks.

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] docs/driver-model: fix typo

[Jonathan Corbet]

On Thu, 15 Sep 2016 22:49:53 +0200
Laurent Navet  wrote:

> No need to be be, just be should be sufficient.

To be be, or not to be be? :)

Applied to the docs tree, thanks.

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v2 0/3] doc-rst:c-domain: fix some issues in the c-domain

[Jonathan Corbet]

On Wed,  7 Sep 2016 09:12:55 +0200
Markus Heiser  wrote:

> according to your remarks I fixed the first and second patch. The third patch 
> is
> resend unchanged;

OK, I've applied the first two, finally.

> > Am 06.09.2016 um 14:28 schrieb Jonathan Corbet :
> >
> > As others have pointed out, we generally want to hide the difference
> > between functions and macros, so this is probably one change we don't
> > want.  
> 
> I read "probably", so there might be a chance to persuade you ;)
> 
> I'm not a friend of *information hiding* and since the index is sorted
> alphabetical it does no matter if the entry is 'FOO (C function)' or 'FOO (C
> macro)'. The last one has the right information e.g. for someone how is 
> looking
> for a macro. FOO is a function-like macro and not a function, if the author
> describes the macro he might use the word "macro FOO" but in the index it is
> tagged as C function.

Information hiding is the only way we can maintain the kernel and stay
sane.  I have a hard time imagining why somebody would be looking for a
macro in particular; the whole idea is that they really shouldn't have to
care.  So my inclination is to leave this one out, sorry.

Thanks,

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 00/17] Create a book for Kernel development

[Jonathan Corbet]

On Wed, 14 Sep 2016 07:52:53 -0300
Mauro Carvalho Chehab  wrote:

> Based on the few comments it got on LKML, it seems people are accepting
> such renames.

I suspect it just hasn't come to the attention of enough people yet.

A quick grep through linux-kernel traffic shows a lot of emails with
references to Documentation/SubmittingPatches.  I'm hesitant to break all
those "links" in the archives, and I fear what people may say to me if we
tell them they have to reference
Documentation/development-process/SubmittingPatches.rst instead.

I'm going to make comments on the individual patches shortly.  Sorry for
being slow - you're a hard guy to keep up with!  But I do have a couple
of overall thoughts.

 - We do need to be careful to avoid sacrificing convenient direct access
   to the text files for nice combined output.  For most of the
   documentation, I don't think there is much of a conflict there.  For a
   few heavily cited files, I worry a bit more.

 - Documentation/development-process is, as I see it now, on the long and
   verbose side.  I know I suggested it!  I wonder if we should use
   "dev-process" (or even just "process") instead?  (Someday I'd like to
   rename Documentation to something like "doc" to be more in line with
   the rest of the kernel's naming, but I'll leave that discussion for
   another day :)

 - We may want to leave some files in place indefinitely.  The list is
   quite small - SubmittingPatches, CodingStyle, maybe not a whole lot
   more - but doing that may well avoid much of the eventual pushback.
   It's worth seeing how hard it would be to get the build process to
   cope with that; otherwise maybe leaving a symlink in place will do.

I'm halfway tempted to revive the documentation thread on the kernel
summit list just to see whether I'm being overly nervous or not.  

Thanks,

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v3 05/21] Documentation/applying-patches.txt: convert it to ReST markup

[Jonathan Corbet]

On Wed, 14 Sep 2016 08:06:34 -0300
Mauro Carvalho Chehab  wrote:

> - use the correct markup to identify each section;
> 
> - Add some blank lines for Sphinx to properly interpret
>   the markups;
> 
> - Remove a blank space on some paragraphs;
> 
> - Fix the verbatim and bold markups;
> 
> - Cleanup the remaining errors to make Sphinx happy.

So I certainly don't have a problem with the changes made to this file, but
there is some discomfort at a higher level:

> +Last update:
> + 2006-01-05

I have to wonder what the value of a document saying how to FTP the patch
and move up to 2.6.13 is in 2016.

Who knows, there might still be value in a discussion of using the patch
tool.  But I think we should seriously consider making a "historical"
section for documents that are nearing or past their expiration dates.

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v3 07/21] Documentation/CodingStyle: Convert to ReST markup

[Jonathan Corbet]

On Wed, 14 Sep 2016 08:06:36 -0300
Mauro Carvalho Chehab  wrote:

> - Fix all chapter identation;
> - add c blocks where needed;

Here is where I think we need a bit of a philosophical discussion...

> - Chapter 1: Indentation
> +Indentation
> +---

You're a fan of having sphinx do the numbering, and I have no problem
understanding why.  But this will defeat people who say "look in chapter 3
of Documentation/CodingStyle".  We're removing a bit of information from
the plain-text file and reserving it for the formatted version.  If we're
really going to do that, we should do it consciously, with the knowledge
that there is a cost involved.

We'll see this even more with SubmittingPatches, where it is quite common
for people to cite the number of the section they think is being violated
in any given situation.

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v3 11/21] Documentation/kernel-docs.txt: convert it to ReST markup

[Jonathan Corbet]

On Wed, 14 Sep 2016 08:06:40 -0300
Mauro Carvalho Chehab  wrote:

> This one required lots of manual work, for it to be properly
> displayed.

And, honestly, I wonder if it was worth it.  This document contains no
entries for any recent documents, many of the links in it are long since
dead, and I honestly doubt it has been helpful to anybody.  If we keep it
should definitely be marked as historical cruft, but I wonder if it's
worth even that much effort?

Thanks,

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v3 13/21] Documentation/SecurityBugs: convert it to ReST markup

[Jonathan Corbet]

On Wed, 14 Sep 2016 08:06:42 -0300
Mauro Carvalho Chehab  wrote:

> Add a name for the document and convert the sections to
> ReST markups.

No objection to the changes (modulo the discussion on section numbers),
but I do wonder whether this one belongs with the process documentation.
This is here for users as much as anybody.  We haven't really begun to
organize user-level docs, but, when we do, I think this maybe belongs
there.

Just a thought...

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v3 05/21] Documentation/applying-patches.txt: convert it to ReST markup

[Joe Perches]

On Fri, 2016-09-16 at 11:10 -0600, Jonathan Corbet wrote:
> On Wed, 14 Sep 2016 08:06:34 -0300 Mauro Carvalho Chehab 
>  wrote:
> - use the correct markup to identify each section;
> - Add some blank lines for Sphinx to properly interpret
>   the markups;
> - Remove a blank space on some paragraphs;
> - Fix the verbatim and bold markups;
> - Cleanup the remaining errors to make Sphinx happy.

> So I certainly don't have a problem with the changes made to this file, but
> there is some discomfort at a higher level:
> +Last update:
> + 2006-01-05
> I have to wonder what the value of a document saying how to FTP the patch
> and move up to 2.6.13 is in 2016.

> Who knows, there might still be value in a discussion of using the patch
> tool.  But I think we should seriously consider making a "historical"
> section for documents that are nearing or past their expiration dates.

Or just entirely delete historical document sections.

All the older kernel sources would still have them so
I don't see much of a need to keep the archival valued
documentation bits in the current kernel source tree.

Suggesting using tools other than git seems wrong today.

And thank you Mauro for the relatively thankless effort
to cleanse and modernize the process documentation.

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v3 17/21] Documentation/SubmittingPatches: convert it to ReST markup

[Jonathan Corbet]

On Wed, 14 Sep 2016 08:06:46 -0300
Mauro Carvalho Chehab  wrote:

>  If you do not have a repository with the current kernel source handy, use
>  git to obtain one.  You'll want to start with the mainline repository,
>  which can be grabbed with:
>  
> -  git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git 
> +::
> +
> +  git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git

Minor nit: you can just put the double colon at the end of the text:

which can be grabbed with::

git clone git://...

...and it will do the right thing.  That helps to make the document look
just a bit less foreign.

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v3 19/21] docs-rst: move HOWTO and mentioned documents to development-process/

[Jonathan Corbet]

On Wed, 14 Sep 2016 08:06:48 -0300
Mauro Carvalho Chehab  wrote:

> In preparation to add those files to the Sphinx build logic,
> move them to development-process/ dir and rename their extension
> to RST.

And this is the crux of the matter, of course :)

I'd like to see this one a bit more widely copied.  For example, Greg
should certainly see the move of the stable kernel docs, and I would want
to have an ack from him.  I guess a lot of the others don't have obvious
targets for cc's, but it's worth a quick think at least.

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH V5] leds: trigger: Introduce a USB port trigger

[Pavel Machek]

On Thu 2016-09-15 15:33:19, Rafał Miłecki wrote:
> On 15 September 2016 at 14:56, Pavel Machek  wrote:
> > On Fri 2016-09-09 13:31:10, Rafał Miłecki wrote:
> >> On 9 September 2016 at 13:05, Greg KH  wrote:
> >> > On Fri, Sep 09, 2016 at 05:34:40PM +0800, Peter Chen wrote:
> >> >> On Thu, Sep 08, 2016 at 06:08:24PM +0200, Rafał Miłecki wrote:
> >> >> > From: Rafał Miłecki 
> >> >> >
> >> >> > This commit adds a new trigger responsible for turning on LED when USB
> >> >> > device gets connected to the selected USB port. This can can useful 
> >> >> > for
> >> >> > various home routers that have USB port(s) and a proper LED telling 
> >> >> > user
> >> >> > a device is connected.
> >> >> >
> >> >> > The trigger gets its documentation file but basically it just requires
> >> >> > enabling it and selecting USB ports (e.g. echo 1 > ports/usb1-1).
> >> >> >
> >> >> > There was a long discussion on design of this driver. Its current 
> >> >> > state
> >> >> > is a result of picking them most adjustable solution as others 
> >> >> > couldn't
> >> >> > handle all cases.
> >> >> >
> >> >> > 1) It wasn't possible for the driver to register separated trigger for
> >> >> >each USB port. Some physical USB ports are handled by more than one
> >> >> >controller and so by more than one USB port. E.g. USB 2.0 physical
> >> >> >port may be handled by OHCI's port and EHCI's port.
> >> >> >It's also not possible to assign more than 1 trigger to a single 
> >> >> > LED
> >> >> >and implementing such feature would be tricky due to syncing 
> >> >> > triggers
> >> >> >and sysfs conflicts with old triggers.
> >> >> >
> >> >> > 2) Another idea was to register trigger per USB hub. This wouldn't 
> >> >> > allow
> >> >> >handling devices with multiple USB LEDs and controllers (hubs)
> >> >> >controlling more than 1 physical port. It's common for hubs to have
> >> >> >few ports and each may have its own LED.
> >> >> >
> >> >> > This final trigger is highly flexible. It allows selecting any USB 
> >> >> > ports
> >> >> > for any LED. It was also modified (compared to the initial version) to
> >> >> > allow choosing ports rather than having user /guess/ proper names. It
> >> >> > was successfully tested on SmartRG SR400ac which has 3 USB LEDs,
> >> >> > 2 physical ports and 3 controllers.
> >> >> >
> >> >> > Another planned feature is support for LED reacting to the USB 
> >> >> > activity.
> >> >> > This can be implemented with another sysfs file for setting mode. The
> >> >> > default mode wouldn't change so there won't be ABI breakage and such
> >> >> > feature can be safely implemented later.
> >> >> >
> >> >>
> >> >> It has such driver at: drivers/usb/common/led.c
> >> >
> >> > Ugh, I thought I had seen something like this before...
> >> >
> >> > Rafał, can you just use this in-kernel code instead?
> >>
> >> I really don't think I can because of all the reasons I carefully
> >> listed in the commit message.
> >>
> >> Have you took a look at that simple driver? It does nothing I need.
> >> Its design doesn't allow implementing features I clearly listed in the
> >> commit message.
> >
> > In any case, the new driver should probably go near the old one, at
> > the very least.
> 
> I can do that. Anyone objects?

I did not have time to study your patches in detail. IIRC there was
something like "directory full of usb IDs". I'm not sure that's a way
to go.

Pavel
-- 
(english) http://www.livejournal.com/~pavelmachek
(cesky, pictures) 
http://atrey.karlin.mff.cuni.cz/~pavel/picture/horses/blog.html
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 00/17] Create a book for Kernel development

[Mauro Carvalho Chehab]

Em Fri, 16 Sep 2016 10:55:02 -0600
Jonathan Corbet  escreveu:

> On Wed, 14 Sep 2016 07:52:53 -0300
> Mauro Carvalho Chehab  wrote:
> 
> > Based on the few comments it got on LKML, it seems people are accepting
> > such renames.  
> 
> I suspect it just hasn't come to the attention of enough people yet.
> 
> A quick grep through linux-kernel traffic shows a lot of emails with
> references to Documentation/SubmittingPatches.  I'm hesitant to break all
> those "links" in the archives, and I fear what people may say to me if we
> tell them they have to reference
> Documentation/development-process/SubmittingPatches.rst instead.

Well, we could use Markus suggestion of keeping a:
Documentation/SubmittingPatches

With a content like:
This file was moved to 
Documentation/development-process/SubmittingPatches.rst

Another alternative would be to try to include this file as:
../SubmittingPatches

But I guess it will still need to be renamed to some extension (.rst),
and we won't be organizing the documentation on a better way.

There's another alternative that would be to use a symbolic link:
SubmittingPatches -> development-process/SubmittingPatches.rst

I guess git supports symlinks (although not sure if such feature is 100%
reliable).

> I'm going to make comments on the individual patches shortly.  Sorry for
> being slow - you're a hard guy to keep up with!

:)

>  But I do have a couple of overall thoughts.
> 
>  - We do need to be careful to avoid sacrificing convenient direct access
>to the text files for nice combined output.  For most of the
>documentation, I don't think there is much of a conflict there.  For a
>few heavily cited files, I worry a bit more.

IMHO, the main reason to port them first is because they're heavily cited
files :)

Those are the important ones that we want every single Kernel developer to
read, specially the newbies.

IMHO, the main challenge for a new developer is to know what are the most
important files at Documentation that they all should read.

Yet, I share your concerns that this would break people's mental links,
but, if we want to organize the house, this needs to be done.

>  - Documentation/development-process is, as I see it now, on the long and
>verbose side.  

Yes, I know! It is almost impossible to avoid having lines smaller than 80
columns when adding references like:

:ref:`file_name `

 for some files there ;)

> I know I suggested it!  I wonder if we should use
>"dev-process" (or even just "process") instead? 

Just "process" sounds good enough for me.

> (Someday I'd like to
>rename Documentation to something like "doc" to be more in line with
>the rest of the kernel's naming, but I'll leave that discussion for
>another day :)

I'm OK with that.

> 
>  - We may want to leave some files in place indefinitely.  The list is
>quite small - SubmittingPatches, CodingStyle, maybe not a whole lot
>more - but doing that may well avoid much of the eventual pushback.
>It's worth seeing how hard it would be to get the build process to
>cope with that; otherwise maybe leaving a symlink in place will do.

I'm not a Sphinx expert, and didn't try to include the files without
renaming them yet. I suspect, however, that sphinx only relies on the
extensions listed at conf.py. Perhaps there's a way to override it
via some extension.

Markus, 

any hints?

> 
> I'm halfway tempted to revive the documentation thread on the kernel
> summit list just to see whether I'm being overly nervous or not.  

Feel free to do it. We may also ask at KS and see how people would
manifest about that.

Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v3 05/21] Documentation/applying-patches.txt: convert it to ReST markup

[Mauro Carvalho Chehab]

Em Fri, 16 Sep 2016 11:10:26 -0600
Jonathan Corbet  escreveu:

> On Wed, 14 Sep 2016 08:06:34 -0300
> Mauro Carvalho Chehab  wrote:
> 
> > - use the correct markup to identify each section;
> > 
> > - Add some blank lines for Sphinx to properly interpret
> >   the markups;
> > 
> > - Remove a blank space on some paragraphs;
> > 
> > - Fix the verbatim and bold markups;
> > 
> > - Cleanup the remaining errors to make Sphinx happy.  
> 
> So I certainly don't have a problem with the changes made to this file, but
> there is some discomfort at a higher level:
> 
> > +Last update:
> > +   2006-01-05  
> 
> I have to wonder what the value of a document saying how to FTP the patch
> and move up to 2.6.13 is in 2016.

As you're commenting my first patch series, I suspect you didn't
see the second one yet ;)
Its subject is:
[PATCH 00/17] Improve documentation for the development-process

There, I read all files that were moved to the development-process
dir, and updated some things. I didn't read yet the files that were
already there, but, as they're newer, I suspect they should be
more synchronized with the status quo.

In the case of this file, I updated it to point to  4.x, removed some
legacy stuff, like the -git tarballs and updated the parts that
mention the -mm kernels, adding a notice about linux-next.
The patch is at:
https://patchwork.kernel.org/patch/9332673/

> 
> Who knows, there might still be value in a discussion of using the patch
> tool.

Well, it teaches how to use the "patch" tool, with can be useful
for newbies. It also explains how the incremental and non-incremental
Kernel patches work. So, I guess it is still useful.

> But I think we should seriously consider making a "historical"
> section for documents that are nearing or past their expiration dates.


> 
> jon



Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v3 07/21] Documentation/CodingStyle: Convert to ReST markup

[Mauro Carvalho Chehab]

Em Fri, 16 Sep 2016 11:13:14 -0600
Jonathan Corbet  escreveu:

> On Wed, 14 Sep 2016 08:06:36 -0300
> Mauro Carvalho Chehab  wrote:
> 
> > - Fix all chapter identation;
> > - add c blocks where needed;  
> 
> Here is where I think we need a bit of a philosophical discussion...
> 
> > -   Chapter 1: Indentation
> > +Indentation
> > +---  
> 
> You're a fan of having sphinx do the numbering, and I have no problem
> understanding why.  But this will defeat people who say "look in chapter 3
> of Documentation/CodingStyle".  We're removing a bit of information from
> the plain-text file and reserving it for the formatted version.  If we're
> really going to do that, we should do it consciously, with the knowledge
> that there is a cost involved.
> 
> We'll see this even more with SubmittingPatches, where it is quite common
> for people to cite the number of the section they think is being violated
> in any given situation.

I see your point. However, AFAICT, there's no way to disable automatic
numbering for LaTeX and PDF formats: it will always generate an index.

It is actually worse than that: the numbering for the LaTeX and PDF
versions of the document don't match with the numbering for html and ePub,
and Sphinx restricts to just one numbered TOC index for the entire document.

Currently, I don't know any way to fix it.

So, keeping the current numeration there will produce a very messy
PDF output, with the two numerations altogether.

Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v3 11/21] Documentation/kernel-docs.txt: convert it to ReST markup

[Mauro Carvalho Chehab]

Em Fri, 16 Sep 2016 11:15:31 -0600
Jonathan Corbet  escreveu:

> On Wed, 14 Sep 2016 08:06:40 -0300
> Mauro Carvalho Chehab  wrote:
> 
> > This one required lots of manual work, for it to be properly
> > displayed.  
> 
> And, honestly, I wonder if it was worth it.  This document contains no
> entries for any recent documents, 

Not sure about that. There are a number of patches from 2016 made by
Luis de Bethencourt updating several stuff.

> many of the links in it are long since
> dead, and I honestly doubt it has been helpful to anybody.

I tested: all links there point to an existing documentation.

Yet, it lacks pointers to more recent printed Kernel books.

> If we keep it
> should definitely be marked as historical cruft, but I wonder if it's
> worth even that much effort?

That's a good question. I don't know the answer.

At the media book, we keep a bibliography updated as we add new stuff
there. I found it to be useful, specially since it mentions some ITU-T
specs that the media framework needs, but this is somewhat different
than what's there.

Maybe we could keep it there for a while and see if people update
it. If not, move it to an "historical" archive or remove it as
a hole.

Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v3 13/21] Documentation/SecurityBugs: convert it to ReST markup

[Mauro Carvalho Chehab]

Em Fri, 16 Sep 2016 11:17:33 -0600
Jonathan Corbet  escreveu:

> On Wed, 14 Sep 2016 08:06:42 -0300
> Mauro Carvalho Chehab  wrote:
> 
> > Add a name for the document and convert the sections to
> > ReST markups.  
> 
> No objection to the changes (modulo the discussion on section numbers),
> but I do wonder whether this one belongs with the process documentation.
> This is here for users as much as anybody.  We haven't really begun to
> organize user-level docs, but, when we do, I think this maybe belongs
> there.

Agreed. I moved it to the dev-process just because it was mentioned at
the HOWTO, but yeah, it would fit more on a doc/user book, together
with README, kernel-parameters.txt, etc.

We can certainly move it to there, and enable intersphinx extension,
to avoid warnings when just one book is compiled.

I guess the big problem with a user book is what should we do with
the top README file. It is the main user book, but it is also something
that a Kernel developer needs.

If you want, I can find some time to work on an user book, but,
before that, I guess we need to define what should we do with the
README file.

My suggestion would be to move its contents to the doc/user/intro.rst
file, and, on its place, add a simple README file that would just
point to the main books inside Documentation, like:

Linux kernel release 4.x 

For the main Kernel user documentation, please see:
Documentation/user

For development documentation, please see:
Documentation/process

For the several API documentation files, please see:
Documentation/media
Documentation/kernel-drivers
Documentation/gpu
...

If you want, I can prepare such patches, but I prefer if we can merge
those two series before that, in order to avoid dependencies between
each patch series.

> 
> Just a thought...
> 
> jon



Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v3 05/21] Documentation/applying-patches.txt: convert it to ReST markup

[Mauro Carvalho Chehab]

Em Fri, 16 Sep 2016 10:20:37 -0700
Joe Perches  escreveu:

> On Fri, 2016-09-16 at 11:10 -0600, Jonathan Corbet wrote:
> > On Wed, 14 Sep 2016 08:06:34 -0300 Mauro Carvalho Chehab 
> >  wrote:
> > - use the correct markup to identify each section;
> > - Add some blank lines for Sphinx to properly interpret
> >   the markups;
> > - Remove a blank space on some paragraphs;
> > - Fix the verbatim and bold markups;
> > - Cleanup the remaining errors to make Sphinx happy.  
> 
> > So I certainly don't have a problem with the changes made to this file, but
> > there is some discomfort at a higher level:
> > +Last update:
> > +   2006-01-05
> > I have to wonder what the value of a document saying how to FTP the patch
> > and move up to 2.6.13 is in 2016.  
> 
> > Who knows, there might still be value in a discussion of using the patch
> > tool.  But I think we should seriously consider making a "historical"
> > section for documents that are nearing or past their expiration dates.  
> 
> Or just entirely delete historical document sections.

IMHO, it is best to just delete, or otherwise someone would be tempted
to convert to ReST.

In the specific case of this one, I still think it is has valuable
information. That's why I updated it on patch 17/17 of the second
patch series.

> All the older kernel sources would still have them so
> I don't see much of a need to keep the archival valued
> documentation bits in the current kernel source tree.
> 
> Suggesting using tools other than git seems wrong today.

Well, while we still generate weekly and per-release patches at
ftp.kernel.org, the information there is still valid.

I have one doubt, however: on this document (and on another converted
one), it mentions about:

ftp.cc.kernel.org, where "cc" is a Country code.

I kept it there (and on another document at the development-process/
dir).

Is it still valid? I did some tests from here, and it didn't seem work.


> And thank you Mauro for the relatively thankless effort
> to cleanse and modernize the process documentation.

Anytime!

Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v3 17/21] Documentation/SubmittingPatches: convert it to ReST markup

[Mauro Carvalho Chehab]

Em Fri, 16 Sep 2016 11:21:17 -0600
Jonathan Corbet  escreveu:

> On Wed, 14 Sep 2016 08:06:46 -0300
> Mauro Carvalho Chehab  wrote:
> 
> >  If you do not have a repository with the current kernel source handy, use
> >  git to obtain one.  You'll want to start with the mainline repository,
> >  which can be grabbed with:
> >  
> > -  git clone 
> > git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git 
> > +::
> > +
> > +  git clone 
> > git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git  
> 
> Minor nit: you can just put the double colon at the end of the text:
> 
> which can be grabbed with::
> 
>   git clone git://...
> 
> ...and it will do the right thing.  That helps to make the document look
> just a bit less foreign.

Oh! good to know! I'll update it on the next patchset.

Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html