Re: [PATCH 00/10] Fix broken documentation references at v5.2-rc1

[Mauro Carvalho Chehab]

Hi Frederico,

Em Wed, 22 May 2019 00:54:48 +0200
Federico Vaga <federico.vaga@xxxxxxxxxx> 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