Re: [PATCH 3/3] docs: Use underscore not hyphen in label

["Tobin C. Harding" <me@tobin.cc>]

On Wed, Feb 06, 2019 at 08:49:38AM +0100, Markus Heiser wrote:
> Am 06.02.19 um 05:27 schrieb Tobin C. Harding:
> > Seems we either change them all or none of them.
> 
> Both are OK .. from the spec ...
> 
> "Simple reference names are single words consisting of alphanumerics plus
> isolated (no two adjacent) internal hyphens, underscores, periods, colons
> and plus signs; no whitespace or other characters are allowed." [1]
> 
> 
> >> Many errors are not reported again in rebuilds.
> >
> > It's more than that.  Seems that no .o files means dependencies are not
> > the same in docs directories to *usual* source code directories, as in
> > this example, a file with an outdated label was not rebuilt since it
> > wasn't touched.
> 
> Right, this is what they call the 'doctree' files (see [2] for build
> phases), one for every source file.  ATM they are located in the hidden
> folder 'output/.doctree'.  OT here, just to mentioning: this will result in
> the folder being exported at the end, e.g. kernel.org:
> 
>   https://www.kernel.org/doc/html/latest/.doctrees/
> 
> > Note to self, always do clean build for docs patches.  Thanks.
> >
> >> To reproduce this error run 'make cleandocs htmldocs' first.  Then you will see
> >> this error message (I'am on current docs-next from Jon using Sphinx v1.8.3 ):
> >>
> >>    Documentation/core-api/mm-api.rst:22: WARNING: undefined label: \
> >>      memory-allocation (if the link has no caption ...)
> >
> > Can confirm I also get this warning,
> ..
> > With patch reverted, on docs-next, I've got 0 'undefined labels'
> > warnings.
> 
> Thanks for verification.
> 
> [1] http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#reference-names
> [2] http://www.sphinx-doc.org/en/master/extdev/index.html#build-phases
> 
> 
>  -- Markus --
> 

Thanks Markus, I appreciate the information.


	Tobin.