Path: csiph.com!xmission!news.snarked.org!news.linkpendium.com!news.linkpendium.com!panix!usenet.stanford.edu!not-for-mail From: Ingo Schwarze Newsgroups: gnu.groff.bug Subject: [bug #58653] Please add back in the mdoc(7) manual Date: Thu, 25 Jun 2020 07:49:48 -0400 (EDT) Lines: 69 Approved: bug-groff@gnu.org Message-ID: References: <20200624-221331.sv200595.64640@savannah.gnu.org> <20200624-225141.sv97361.96482@savannah.gnu.org> <20200625-071246.sv200595.41215@savannah.gnu.org> <20200625-114948.sv97361.64018@savannah.gnu.org> NNTP-Posting-Host: lists.gnu.org Mime-Version: 1.0 Content-Type: text/plain;charset=UTF-8 X-Trace: usenet.stanford.edu 1593085790 16183 209.51.188.17 (25 Jun 2020 11:49:50 GMT) X-Complaints-To: action@cs.stanford.edu To: Ingo Schwarze , , bug-groff@gnu.org Envelope-to: bug-groff@gnu.org X-PHP-Originating-Script: 1001:sendmail.php X-Savane-Server: savannah.gnu.org:443 [209.51.188.72] X-Savane-Project: groff X-Savane-Tracker: bugs X-Savane-Item-ID: 58653 User-Agent: Mozilla/5.0 (X11; OpenBSD amd64; rv:77.0) Gecko/20100101 Firefox/77.0 X-Apparently-From: 87.173.117.25 (Savane authenticated user schwarze) In-Reply-To: <20200625-071246.sv200595.41215@savannah.gnu.org> X-BeenThere: bug-groff@gnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: "Bug reports for the GNU version of nroff, troff et al" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-Mailman-Original-Message-ID: <20200625-114948.sv97361.64018@savannah.gnu.org> X-Mailman-Original-References: <20200624-221331.sv200595.64640@savannah.gnu.org> <20200624-225141.sv97361.96482@savannah.gnu.org> <20200625-071246.sv200595.41215@savannah.gnu.org> Xref: csiph.com gnu.groff.bug:1884 Follow-up Comment #3, bug #58653 (project groff): You say "i wish you had mentioned this before". Granted, it would have been helpful, and i wanted to. But there isn't time to answer all questions i could usefully respond to, so it fell through the cracks. I estimate roughly 80% fall through the cracks due to lack of time. I tend to prioritize those answers that allow positive action over those refuting bad ideas. Opening this bug forced me to answer just to make sure no harm is done. You say "but beginners need something simpler". I contest that. It's not because i'm an expert on mdoc(7). When learning a completely new language totally from scratch, i typically go for the formal standard / formal language definition (or the reference manual if there is no completely formal document), and certainly not for the user manual or tutorial, which usually is a total waste of time even during the first two or three hours of learning. Of course that approach doesn't work for very complex topics like quantum field theory where you first have to understand more than half a dozen layers of mathematical abstractions, each built on top of the simpler ones, but it works just fine for anything that can be readily understood just based on natural language, without any previous knowledge of any kind, like a markup language as intentionally trivial as mdoc, and even for just about any programming language. Just train your reading skills to quickly extract the information you need from a precise, concise text without reading all the words. You say "writing good docs that are correct, complete, and concise takes time, and they tend to degrade over time from accretion". Absolutely. I write a lot of documentation, my average time per function is over two hours (mostly measured documenting crypto/TLS libraries, but i write lots of other stuff, too). Some functions take up to eight hours. On top of that, good documentation requires good API/UI design, or you have lost before you even start. Then, if the API/UI develops feature creep over time, the docs will degrade at least as much as the code. Fortunately, no such degradation happened in mdoc, i took care of that during the last decade, adding just one single macro in ten years and during the same time deprecating more than half a dozen and removing traps from a few others. You say "but even confusing information is still helpful". No it is not. There is no time to maintain it. Unmaintained, it causes confusion and questions which no one has time to handle. Why do you think we spent the time to get the horrible document exterminated? To save us more time and confusion. afterwards. You name some downsides of groff_mdoc(7). Yes, the IDIOSYNCRASIES section is a bit wordy, in particular being near the beginning of the page, but it's trivial to see even for a beginner that you can skip it during the first reading. I work relatively little on groff documentation because i maintain mandoc documentation. Both have essentially identical content arranged in slightly different style, and since i see no way to prevent this duplication, i think we can at least make it partly useful by having it maintained by different people, such that users can pick the style they understand more easily. If groff_mdoc(7) is too wordy for you, especially near the beginning, you will probably like the more concise mandoc mdoc(7) manual better. Also, the high-level "what is this all about" stuff useful for beginners is easier to find in mandoc mdoc(7) than in groff_mdoc(7). Certainly no need for a third. _______________________________________________________ Reply to this item at: _______________________________________________ Message sent via Savannah https://savannah.gnu.org/