On Tue, Aug 07, 2018 at 07:14:05AM -0600, Jonathan Corbet wrote: > On Tue, 7 Aug 2018 12:48:44 +1000 > "Tobin C. Harding" <me@xxxxxxxx> wrote: > > > How about these steps: > > > > 1. start with foo.txt > > 2. do typo and grammar fixes (any number of patches). > > 3. rename to foo.rst, do whitespace changes, code snippet > > indentation, heading adornments, update references to this file. > > (single patch). > > 4. Fix up references in the file text to use RST (i.e :ref: blah) > > 5. Fix up RST markers (backticks etc). (any number of patches) > > That can certainly work; just don't call it foo.rst until it actually is a > valid RST file. > > And, of course, go easy with the later steps and try to avoid the > temptation to mark up everything; we really want to preserve the > readability of the plain-text files. Yeah I get over zealous sometimes, I'll keep it in mind. What is the current view on references embedded in the text versus a local label with the full reference at the bottom of the file. I've seen both and do not know which is _more_ readable? 1. some random text referencing :ref:`Documentation/path/to/file.rst <label>` and more text 2. some random text referencing `file`_ and more text ... .. Links .. _file path/to/file.rst: Although the later form is found in Documentation/ it does not seem work for local build (since the path is relative) or am I doing something wrong with my local build? And for the first form I could not get the html link produced to work if the <label> was omitted - this label seems superfluous if it is to the top of the file (I've already added a couple of such labels). These are minor issues, answer only if and when you have time. thanks, Tobin. -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
