Re: [PATCH] howto: Use all-space indentation in ASCII art
Those text files are installed as documentation (at least on my distribution). That's probably a distribution bug (or a git makefile bug, depending on how you look at it). It would be better to ship the HTML documentation, converted to text, instead of keeping the version with markup including occasional random \ signs, linkgit:, ``, etc. What distribution do you use? (As maintainer of packaging for a Linux distro, I know at least one that is guilty of this.) From the AcsiiDoc Home Page: =begin quote= You write an AsciiDoc document the same way you would write a normal text document, there are no markup tags or weird format notations. AsciiDoc files are designed to be viewed, edited and printed directly or translated to other presentation formats using the asciidoc(1) command. =end quote= So, the asciidoc "source" files should be readable in their unprocessed form. And, not using tabs in ASCII art doesn't appear to have any downside. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] howto: Use all-space indentation in ASCII art
On Tue, Jul 16, 2013 at 11:26:27AM -0700, Jonathan Nieder wrote: > Dirk Wallenstein wrote: > > > Those text files are installed as documentation (at least on my > > distribution). > > That's probably a distribution bug (or a git makefile bug, depending > on how you look at it). It would be better to ship the HTML > documentation, converted to text, instead of keeping the version with > markup including occasional random \ signs, linkgit:, ``, etc. They are also installed if I only use Git's makefile. > > What distribution do you use? (As maintainer of packaging for a Linux > distro, I know at least one that is guilty of this.) Ubuntu. As an aside, I had to run manual creation as root. Otherwise it did hang (XMLTO). Is that an Ubuntu bug? Sorry, just because you seem to know about this. -- Cheers, Dirk -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] howto: Use all-space indentation in ASCII art
Dirk Wallenstein wrote: > Those text files are installed as documentation (at least on my distribution). That's probably a distribution bug (or a git makefile bug, depending on how you look at it). It would be better to ship the HTML documentation, converted to text, instead of keeping the version with markup including occasional random \ signs, linkgit:, ``, etc. What distribution do you use? (As maintainer of packaging for a Linux distro, I know at least one that is guilty of this.) Thanks, Jonathan -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] howto: Use all-space indentation in ASCII art
On Tue, Jul 16, 2013 at 10:13:28AM -0700, Junio C Hamano wrote: > > Why would you want to limit those files to be source for HTML only? > > > > The HTML after this patch is still fine. > > Have you thought the reason why the formatted result _before_ the patch is > good? No, as I said, *.txt suffixes tell me there is text in there and not source code. But what is more important is that they are installed (by Git) as is (obviously) into share/doc. I'm happy to learn about the conversion through these posts, but the installation is flawed. > These *.txt files are asciidoc formatted source files. They are meant > to be easy to read and edit without distracting mark-ups (unlike roff > and html), but with one big precondition: your tab-width ought to be > 8. That is how asciidoc expands the tab when producing the formatted > output, and that is why the formatted result _before_ the patch is > good. asciidoc replaces the other spaces in the sketch with spaces in the result. Hard to believe it stops doing that if it is accidentally a sequence of 8 spaces. And spaces are invisible by design. Whitespace only distracts if it leads to a wrong result. > > Expanding these tabs to all spaces do not buy us anything, other than > source code bloat, and with one downside. Correctness maybe, if you open them in an editor to read them. Imagine the code bloat when the installation procedure expands the tabs so that the final installation is correct. > It would give a false impression that it somehow is OK to open these > *.txt files with a wrong tab-width setting, and even worse, edit them. > You may even type a new tab yourself to indent by 4 places, and > formatted result will be broken by such a person. Luckily there are whitespace checks for mixed space and/or tab-indent. The right approach would probably be to have no tabs indent in any of these files. I'm happy to assist ;) > > It would signal that your tab-width setting is not suitable to > view/edit these files if the elements in the illustration do not line > up. View it as a bonus safety feature ;-) gitattributes could solve that much more reliable if there wasn't any tab indentation allowed. In the end, this is installed as documentation with a requirement on the tab-width of any reader application used. The easiest and most foolproof solution without introducing errors is to simply expand these tabs. Again, the current installation is flawed. -- Cheers, Dirk -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] howto: Use all-space indentation in ASCII art
> Why would you want to limit those files to be source for HTML only? > > The HTML after this patch is still fine. Have you thought the reason why the formatted result _before_ the patch is good? These *.txt files are asciidoc formatted source files. They are meant to be easy to read and edit without distracting mark-ups (unlike roff and html), but with one big precondition: your tab-width ought to be 8. That is how asciidoc expands the tab when producing the formatted output, and that is why the formatted result _before_ the patch is good. Expanding these tabs to all spaces do not buy us anything, other than source code bloat, and with one downside. It would give a false impression that it somehow is OK to open these *.txt files with a wrong tab-width setting, and even worse, edit them. You may even type a new tab yourself to indent by 4 places, and formatted result will be broken by such a person. It would signal that your tab-width setting is not suitable to view/edit these files if the elements in the illustration do not line up. View it as a bonus safety feature ;-) -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] howto: Use all-space indentation in ASCII art
On Mon, Jul 15, 2013 at 03:00:17PM -0700, Junio C Hamano wrote: > Dirk Wallenstein writes: > > > Keep the sketch aligned independent of the tabstop width used. > > Thanks. > > This is a source text to be formatted into HTML, isn't it? > > In our sources, a HT indents to multiple of 8 columns. As long as > the output HTML produced from the source can be seen on a terminal > with any tab-width correctly, I do not see any reason to apply this > patch. > > Am I missing something??? > Those text files are installed as documentation (at least on my distribution). They have a *.txt suffix, which tells me that they are meant to be read. If those would ever be opened with a text editor where the user has set the default tabstop width to something other than 8 it would teach something nonsensical. Not to mention if those files would have been printed with the wrong setting. Why would you want to limit those files to be source for HTML only? The HTML after this patch is still fine. -- Cheers, Dirk -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] howto: Use all-space indentation in ASCII art
Dirk Wallenstein writes: > Keep the sketch aligned independent of the tabstop width used. Thanks. This is a source text to be formatted into HTML, isn't it? In our sources, a HT indents to multiple of 8 columns. As long as the output HTML produced from the source can be seen on a terminal with any tab-width correctly, I do not see any reason to apply this patch. Am I missing something??? -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
