doc:it_IT: kernel-hacking translation

doc:it_IT: kernel-hacking translation

[Federico Vaga]

Ciao Jon,

This small set of patches introduces the kernel-hacking translation in Italian
and fix the locking.rst internal links. I do not know if this is a problem
with **my** Sphinx environment but these links were not working.


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

[PATCH 1/2] doc:hacking: add labels

[Federico Vaga]

Apparently some local links are not properly generated in locking.rst.
This patch use the ':ref:' directive to add the link to the section label.

Signed-off-by: Federico Vaga <federico.vaga@vaga.pv.it>
---
 Documentation/kernel-hacking/locking.rst | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/Documentation/kernel-hacking/locking.rst b/Documentation/kernel-hacking/locking.rst
index f937c0fd11aa..574fc92a6f20 100644
--- a/Documentation/kernel-hacking/locking.rst
+++ b/Documentation/kernel-hacking/locking.rst
@@ -177,7 +177,7 @@ perfect world).
 
 Note that you can also use :c:func:`spin_lock_irq()` or
 :c:func:`spin_lock_irqsave()` here, which stop hardware interrupts
-as well: see `Hard IRQ Context <#hardirq-context>`__.
+as well: see :ref:`Hard IRQ Context <hardirq-context>`.
 
 This works perfectly for UP as well: the spin lock vanishes, and this
 macro simply becomes :c:func:`local_bh_disable()`
@@ -228,7 +228,7 @@ The Same Softirq
 ~~~~~~~~~~~~~~~~
 
 The same softirq can run on the other CPUs: you can use a per-CPU array
-(see `Per-CPU Data <#per-cpu>`__) for better performance. If you're
+(see :ref:`Per-CPU Data <per-cpu>`) for better performance. If you're
 going so far as to use a softirq, you probably care about scalable
 performance enough to justify the extra complexity.
 
@@ -243,6 +243,8 @@ You'll need to use :c:func:`spin_lock()` and
 tasklet, different softirq or the same or another softirq: any of them
 could be running on a different CPU.
 
+.. _`hardirq-context`:
+
 Hard IRQ Context
 ================
 
@@ -875,6 +877,8 @@ Alan Cox says, “Lock data, not code”.
 Common Problems
 ===============
 
+.. _`deadlock`:
+
 Deadlock: Simple and Advanced
 -----------------------------
 
@@ -1247,6 +1251,8 @@ The benefit here is that the reference count is not written to: the
 object is not altered in any way, which is much faster on SMP machines
 due to caching.
 
+.. _`per-cpu`:
+
 Per-CPU Data
 ------------
 
@@ -1294,6 +1300,8 @@ Naturally, this is slower than just a :c:func:`spin_lock_irq()`
 call, so it only makes sense if this type of access happens extremely
 rarely.
 
+.. _`sleeping-things`:
+
 What Functions Are Safe To Call From Interrupts?
 ================================================
 
-- 
2.17.1

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

Re: doc:it_IT: kernel-hacking translation

[Federico Vaga]

On Saturday, July 7, 2018 12:05:15 AM CEST Federico Vaga wrote:
> Ciao Jon,
> 
> This small set of patches introduces the kernel-hacking translation in
> Italian and fix the locking.rst internal links. I do not know if this is
> a problem with **my** Sphinx environment but these links were not
> working.

And I forget to say that I changed the header part (translation 
information). The idea is that metadata field are less invasive, cleaner, 
than notes when rendered in HTML. I think this (metadata fields) is better. 
If you agree I will change what I did in doc-guide.

-- 
Federico Vaga
http://www.federicovaga.it/


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

Re: [PATCH 1/2] doc:hacking: add labels

[Jonathan Corbet]

On Sat,  7 Jul 2018 00:05:16 +0200
Federico Vaga <federico.vaga@vaga.pv.it> wrote:

> Apparently some local links are not properly generated in locking.rst.
> This patch use the ':ref:' directive to add the link to the section label.
> 
> Signed-off-by: Federico Vaga <federico.vaga@vaga.pv.it>
> ---
>  Documentation/kernel-hacking/locking.rst | 12 ++++++++++--
>  1 file changed, 10 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/kernel-hacking/locking.rst b/Documentation/kernel-hacking/locking.rst
> index f937c0fd11aa..574fc92a6f20 100644
> --- a/Documentation/kernel-hacking/locking.rst
> +++ b/Documentation/kernel-hacking/locking.rst
> @@ -177,7 +177,7 @@ perfect world).
>  
>  Note that you can also use :c:func:`spin_lock_irq()` or
>  :c:func:`spin_lock_irqsave()` here, which stop hardware interrupts
> -as well: see `Hard IRQ Context <#hardirq-context>`__.
> +as well: see :ref:`Hard IRQ Context <hardirq-context>`.

Actually, the real problem here was that the #tag was wrong.  I've applied
the following instead.

Thanks,

jon

docs: Fix the reference labels in Locking.rst

Two jump tags were misspelled, leading to non-working cross-reference
links.

Reported-by: Federico Vaga <federico.vaga@vaga.pv.it>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/kernel-hacking/locking.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/kernel-hacking/locking.rst b/Documentation/kernel-hacking/locking.rst
index f937c0fd11aa..9cc036ff57b9 100644
--- a/Documentation/kernel-hacking/locking.rst
+++ b/Documentation/kernel-hacking/locking.rst
@@ -177,7 +177,7 @@ perfect world).
 
 Note that you can also use :c:func:`spin_lock_irq()` or
 :c:func:`spin_lock_irqsave()` here, which stop hardware interrupts
-as well: see `Hard IRQ Context <#hardirq-context>`__.
+as well: see `Hard IRQ Context <#hard-irq-context>`__.
 
 This works perfectly for UP as well: the spin lock vanishes, and this
 macro simply becomes :c:func:`local_bh_disable()`
@@ -228,7 +228,7 @@ The Same Softirq
 ~~~~~~~~~~~~~~~~
 
 The same softirq can run on the other CPUs: you can use a per-CPU array
-(see `Per-CPU Data <#per-cpu>`__) for better performance. If you're
+(see `Per-CPU Data <#per-cpu-data>`__) for better performance. If you're
 going so far as to use a softirq, you probably care about scalable
 performance enough to justify the extra complexity.
 
-- 
2.17.1

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

Re: [PATCH 2/2] doc:it_IT: translation for kernel-hacking

[Jonathan Corbet]

On Sat,  7 Jul 2018 00:05:17 +0200
Federico Vaga <federico.vaga@vaga.pv.it> wrote:

> This patch includes the kernel-hacking translation in Italian (both
> hacking.rst and locking.rst).
> 
> It adds also the anchors for the english kernel-hacking documents.

Applied, thanks.  Though I do have to wonder a bit, since these documents
are ancient and haven't seen a lot of maintenance in recent times...

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

Re: [PATCH 2/2] doc:it_IT: translation for kernel-hacking

[Federico Vaga]

I know, but I believe they are still good documents if read with a bit of 
pragmatism: many concepts there are evergreen. Then, it clearly says 
"unreliable" ;P

Your wonder, make me wonder. Generally speaking, how readers can understand 
how old is a document or if it still correct (in the sense that the document 
and the correspondent code are in sync)? Clearly here it says that it has been 
written for Linux 2.6, but most documents do not say anything about the last 
significant review/update. This let people think that documentation and code 
are always in sync. How this is handled? Just by enforcing people to update 
the documentation when they change, for example, an interface that has been 
documented?

On Friday, July 27, 2018 12:23:30 AM CEST Jonathan Corbet wrote:
> On Sat,  7 Jul 2018 00:05:17 +0200
> 
> Federico Vaga <federico.vaga@vaga.pv.it> wrote:
> > This patch includes the kernel-hacking translation in Italian (both
> > hacking.rst and locking.rst).
> > 
> > It adds also the anchors for the english kernel-hacking documents.
> 
> Applied, thanks.  Though I do have to wonder a bit, since these documents
> are ancient and haven't seen a lot of maintenance in recent times...
> 
> jon


-- 
Federico Vaga
http://www.federicovaga.it/


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

Re: [PATCH 2/2] doc:it_IT: translation for kernel-hacking

[Jonathan Corbet]

On Fri, 27 Jul 2018 09:46:47 +0200
Federico Vaga <federico.vaga@vaga.pv.it> wrote:

> Generally speaking, how readers can understand 
> how old is a document or if it still correct (in the sense that the document 
> and the correspondent code are in sync)? 

We don't have a good answer to that, really.  Some of our docs are
up-to-the-second current, and others still talk about how to find out
which vacuum tube has gone bad in your system.  It's a trap for our
readers, unfortunately.  My plan has been to try to bring some more order
to Documentation/ first, hopefully cleaning things up a bit on the way.


> How this is handled? Just by enforcing people to update 
> the documentation when they change, for example, an interface that has been 
> documented?

magari ... talk of such enforcement is a recurring thing, but nobody has
the will to actually do that.  

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