A report from the documentation maintainer

Posted Oct 27, 2016 5:28 UTC (Thu) by xtifr (guest, #143)
Parent article: A report from the documentation maintainer

Wow, ok, not really my place to criticize any kernel devs, but the ones who don't want to "remove" obsolete documentation--do they not understand how git works? I am, frankly, a bit boggled.

I'm less boggled—but still slightly—by the directory-name-is-too-long crowd. Are there really that many people who use neither a point-and-click interface nor filename completion? (And are there really that many people working on the kernel who find typing that difficult?)

Anyway, thanks for the report. Definitely interesting, and very promising, though I'm sorry to hear about the LaTeX-related struggles.

to post comments

A report from the documentation maintainer

Posted Oct 27, 2016 14:10 UTC (Thu) by niner (guest, #26151) [Link] (9 responses)

There are more than 2300 pointers at Documentation files in the kernel source in comments. None of them could have used auto completion or point and click.

Documentation/ references

Posted Oct 27, 2016 14:15 UTC (Thu) by corbet (editor, #1) [Link] (8 responses)

Heh...that's a bit of a disincentive to moving Documentation/, of course...:)

Even more common, though, is references in email. People type those every day, and I've already gotten complaints about making the path to files longer than it is already.

Documentation/ references

Posted Oct 28, 2016 20:30 UTC (Fri) by HIGHGuY (subscriber, #62277) [Link] (7 responses)

git supports soft-links, so it should be easy to let docs -> Documentation, followed by a period of clean-ups in the code and ultimately moving Documentation over docs or swapping things around with Documentation -> docs. The latter might accomodate weblinks pointing to kernel.org git repo's and similar things.

Is there some peculiar reason why that wouldn't be allowed? (checkout on FAT or NTFS filesystems perhaps >:-] )

Documentation/ references

Posted Oct 29, 2016 0:12 UTC (Sat) by flussence (guest, #85566) [Link]

How do you propose fixing all the other links that point to kernel trees hosted somewhere other than kernel.org? Or do those just stay broken forever?

Documentation/ references

Posted Oct 31, 2016 13:19 UTC (Mon) by cesarb (subscriber, #6266) [Link] (5 responses)

> (checkout on FAT or NTFS filesystems perhaps >:-] )

Checkout on FAT or NTFS is already not possible, since the kernel has files which differ only on case.

Documentation/ references

Posted Oct 31, 2016 15:39 UTC (Mon) by zdzichu (subscriber, #17118) [Link] (4 responses)

NTFS is case-sensitive, so there isn't a problem.

Documentation/ references

Posted Oct 31, 2016 16:21 UTC (Mon) by Cyberax (✭ supporter ✭, #52523) [Link] (3 responses)

Not true. NTFS is case-preserving but not case-sensitive. You _can_ create files on NTFS that differ only in case, but it will cause a lot of problems (like not being able to delete them using regular tools).

Documentation/ references

Posted Nov 7, 2016 4:10 UTC (Mon) by JanC_ (guest, #34940) [Link] (2 responses)

NTFS is case sensitive.

The NT kernel supports case sensitive file systems.

The Windows subsystems & applications using it have problems with it.

Documentation/ references

Posted Nov 7, 2016 4:44 UTC (Mon) by Cyberax (✭ supporter ✭, #52523) [Link] (1 responses)

NTFS stores case mapping in a metafile called "$UpCase". You are free to ignore it and write files named "Foo" and "FOO" but this will break the Windows API.

Documentation/ references

Posted Nov 7, 2016 12:16 UTC (Mon) by mathstuf (subscriber, #69389) [Link]

It is fun to use a Samba share from Linux and create files Windows has problems with and explore that way. Creating a file named CON gets mangled in Explorer to some string X. Create a file named X and Explorer cannot delete the CON file until the other disappears (selecting the right file does not work; deletion is by name). Similar shenanigans happen with mixed cases.

A report from the documentation maintainer

Posted Oct 27, 2016 17:54 UTC (Thu) by mchehab (subscriber, #41156) [Link] (1 responses)

> Interestingly, there is significant disagreement over the removal of ancient, obsolete documentation. Do we really need, say, documentation from 1996 (http://static.lwn.net/kerneldoc/admin-guide/bug-hunting.html)

> > Wow, ok, not really my place to criticize any kernel devs, but the ones who don't want to "remove" obsolete documentation--do they not understand how git works?

My point, with regards to bug_hunting.html is that, except for one section there that it is really old (Finding it the old way), the remaining file provide useful tips that are still useful, like using git bisect to identify the bug source, and objdump/gdb to identify what part of the source code caused the bug.

So, IMHO, instead of dropping everything, we should drop just the outdated section, and improve the remaining document to reflect the current practices, like what I proposed on this patch:

https://marc.info/?l=linux-doc&m=147752366022236&w=2

A report from the documentation maintainer

Posted Nov 4, 2016 12:54 UTC (Fri) by Wol (subscriber, #4433) [Link]

Or, what I'm trying to do on the linux raid wiki, have a section for obsolete stuff. So I've linked all the out-of-date stuff there, and as I rewrite it, the new stuff replaces the old on the main pages.

So all the old stuff is still there if it's wanted, but it's in a section flagged as "obsolete".

Cheers,
Wol

A report from the documentation maintainer

Posted Oct 27, 2016 20:40 UTC (Thu) by flussence (guest, #85566) [Link] (4 responses)

I find the proposal to rename the directory completely ridiculous. Too long? "D<tab>" is one character shorter than "do<tab>".

And it's *much* faster to type than "d<tab><beat><tab><shell beeps and displays ambiguous results><cursing at whoever proposed this>o<tab>".

I get the feeling the people asking for that change are just pedants that don't actually use the documentation.

A report from the documentation maintainer

Posted Oct 30, 2016 8:25 UTC (Sun) by dirtyepic (guest, #30178) [Link] (3 responses)

Believe it or not, some people have the ability to type into things other than shells.

A report from the documentation maintainer

Posted Nov 2, 2016 12:02 UTC (Wed) by robbe (guest, #16131) [Link] (2 responses)

If your text editor cannot complete words, maybe consider switching?

The example of e-mail was brought up. I guess you are surrounding the reference to a file under Documentation/ with one or more sentences. Containing complete words (not abbreviations) for the most part.

A report from the documentation maintainer

Posted Nov 3, 2016 15:22 UTC (Thu) by Wol (subscriber, #4433) [Link] (1 responses)

If your text editor can complete words, maybe consider ditching it?

I consider the text completion in Kate (my favourite editor) an absolute PAIN. Likewise date completion in word processors. Etc etc. If I *don't ask for it*, then I *don't want it*. How many times I have I had the stuff I'm typing corrupted by autocomplete, autocorrect, etc? Far too many!!! And they usually use something like "return" to indicate that I want the change, so if I'm gaily typing away and put this thing at the end of the line, I get the auto-change that I didn't ask for because the editor thinks I did!

Getting the UI on this right is *NOT* easy, and then giving it to a touch typist who has been trained *NOT* to look at the screen is going to cause an awful lot of grief!

Cheers,
Wol

A report from the documentation maintainer

Posted Nov 3, 2016 18:18 UTC (Thu) by mathstuf (subscriber, #69389) [Link]

You're talking about autocompletion. Supporting completion behind a keybinding (e.g., <C-n> or <C-p> in Vim) is not the same thing.