Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67;
Date:   Tue, 21 May 2019 21:26:00 -0300
From:   Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
To:     Federico Vaga <federico.vaga@vaga.pv.it>
Cc:     Linux Doc Mailing List <linux-doc@vger.kernel.org>,
        Mauro Carvalho Chehab <mchehab@infradead.org>,
        linux-kernel@vger.kernel.org, Jonathan Corbet <corbet@lwn.net>
Subject: Re: [PATCH 00/10] Fix broken documentation references at v5.2-rc1
Message-ID: <20190521212600.39bc341c@coco.lan>
In-Reply-To: <51951662.QppCrsbGrr@harkonnen>
References: <cover.1558362030.git.mchehab+samsung@kernel.org>
        <51951662.QppCrsbGrr@harkonnen>
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk

Hi Frederico,

Em Wed, 22 May 2019 00:54:48 +0200
Federico Vaga <federico.vaga@vaga.pv.it> escreveu:

> On Monday, May 20, 2019 4:47:29 PM CEST Mauro Carvalho Chehab wrote:
> > There are several broken Documentation/* references within the Kernel
> > tree. There are some reasons for several of them:
> > 
> > 1. The acpi and x86 documentation files were renamed, but the
> >    references weren't updated;
> > 2. The DT files have been converted to JSON format, causing them
> >    to be renamed;
> > 3. Translated files point to future translation work still pending merge
> >    or require some action from someone that it is fluent at the
> >    translated language;  
> 
> Hi Mauro

My main goal with this patchset is to get as close as possible to zero
warnings, as this helps me on rebasing a documentation patch series
I wrote with renames hundreds of file from .txt to .rst.

In the case of (3), the scripts/documentation-file-ref-check was unable to
find some files pointed by Italian and Chinese translations. So, after
this series, it will keep pointing for broken links there.

> I am not sure to get what you mean in terms of actions but I think you are 
> referring to the "empty" files I added in the Italian translations. I added 
> those files to avoid broken links; the alternative would have been to not 
> write those links or to point directly to the main document, but in both 
> cases it easy to forget to update them later.
> I chose to have links to "empty" files so that the document does 
> not need to be updated later.
> 
> If you are not referring to those files than I am not understanding, can you 
> point to a clear example?

What I meant is that I can barely read Italian and have no glue on
Chinese. So, I can't really address those properly :-)
So, basically, it should be up to someone else fluent on such
languages to address those.

Btw, I understand why you pointed to some non-existing files: 
translating the Kernel's documents takes a lot of time[1].

[1] If I was doing a translation, I would probably have opted to keep 
pointing to the English doc and have a script to point me links to
non-translated docs, but your way also works. The only drawback is that
the script will keep pinpointing to translations with broken links,
while the translation is not complete.

Thanks,
Mauro