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;
From:   Federico Vaga <federico.vaga@vaga.pv.it>
To:     Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
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
Date:   Wed, 22 May 2019 22:18:23 +0200
Message-ID: <4613410.CTphFSq3dd@harkonnen>
In-Reply-To: <20190521212600.39bc341c@coco.lan>
References: <cover.1558362030.git.mchehab+samsung@kernel.org> <51951662.QppCrsbGrr@harkonnen> <20190521212600.39bc341c@coco.lan>
MIME-Version: 1.0
Content-Transfer-Encoding: 7Bit
Content-Type: text/plain; charset="us-ascii"
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk

On Wednesday, May 22, 2019 2:26:00 AM CEST Mauro Carvalho Chehab wrote:
> 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].

More than non-existing the file *should* be there, only that it says the 
translation is pending. So the tool should find the file without complaining.

I did not pay enough attention; I was not aware about the existence of that 
tool. Now that I filled my ignorance with a bit of knowledge I will use to fix 
those documents. Thank you

> 
> [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