Re: [PATCH] Documentation/technical/api-hashmap: Remove source highlighting
Anders Kaseorg ande...@mit.edu writes: How bad does the documentation look with the patch applied (I know how bad it looks without source-highlight installed)? If it is not too bad, then it sounds like a sensible solution to drop the highlight markup unconditionally like the patch that started this thread does, taking the common denominator approach. You seem to agree, and I do not object, either. Original version with syntax-highlight installed (pretty): http://web.mit.edu/andersk/Public/api-hashmap/old-highlight.html Original version with syntax-highlight missing (corrupted): http://web.mit.edu/andersk/Public/api-hashmap/old-no-highlight.html Patched version (boring but readable): http://web.mit.edu/andersk/Public/api-hashmap/patched.html Thanks. I've queued the patch for v2.0 and the comparison between the first and the third clearly shows that it is the right thing to do ;-). -- 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] Documentation/technical/api-hashmap: Remove source highlighting
Anders Kaseorg ande...@mit.edu writes: Yes; when I noticed this failure, I asked Jonathan to add source-highlight as a build dependency in Debian (https://bugs.debian.org/745591). But then Ubuntu forked the packaging to revert this change (https://bugs.launchpad.net/bugs/1316810), because source-highlight in the community-supported universe repository is not allowed to be a build dependency ... The reasoning and solution Ubuntu has sounds sensible *but* it also soudns like it is incomplete. If Ubuntu does not want to use highlight, it can apply a change like the patch in question as part of their fork to make the end result consistent and they are failing to do so. If the tooling do not use highlight, the source should not require highlight, either. It is ultimately their bug. It however *is* our business, as their upstream, to make it easier for distros that want to use and distros that do not want to depend on highlight, and aiming for a solution that relieves Ubuntu or any other distros from needing to carry one more patch is a good thing. How bad does the documentation look with the patch applied (I know how bad it looks without source-highlight installed)? If it is not too bad, then it sounds like a sensible solution to drop the highlight markup unconditionally like the patch that started this thread does, taking the common denominator approach. You seem to agree, and I do not object, either. But I don’t that would be worth it just to make one page of the API documentation a little more colorful (and it sounds like you agree). -- 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] Documentation/technical/api-hashmap: Remove source highlighting
On Mon, 19 May 2014, Junio C Hamano wrote: If Ubuntu does not want to use highlight, it can apply a change like the patch in question as part of their fork to make the end result consistent and they are failing to do so. Sure, Ubuntu can apply that patch, but the larger problem remains: if the Ubuntu packaging is even slightly different from Debian’s, it is no longer eligible for automatic synchronization from Debian. When that has happened in the past, the result was that the Ubuntu version languished far behind the Debian version, because Canonical doesn’t have the manpower to manually merge every Debian update. Ubuntu 9.04 shipped with Git 1.6.0.4 instead of 1.6.2.4 because they had failed to update their packaging after patching out a dependency on cvsps. If this Ubuntu nonsense were obstructing something important upstream, then of course I would be yelling at Ubuntu to get their act together; in that case, I filed a main inclusion report to get Canonical to officially support cvsps (https://bugs.launchpad.net/bugs/369111) so Ubuntu could drop their patch. But here we’re talking about syntax highlighting in one page of internal documentation that basically nobody is going to read, and that argument wouldn’t carry any weight. We could put the patch into Debian instead of Ubuntu to eliminate the Ubuntu delta; Jonathan has been friendly enough to Ubuntu that I think he would grudgingly agree. But I’m submitting it upstream because other distros will eventually run into the same problem: there’s no obvious cue that source-highlight needs to be added as a new dependency besides a warning message buried in the middle of the build log. How bad does the documentation look with the patch applied (I know how bad it looks without source-highlight installed)? If it is not too bad, then it sounds like a sensible solution to drop the highlight markup unconditionally like the patch that started this thread does, taking the common denominator approach. You seem to agree, and I do not object, either. Original version with syntax-highlight installed (pretty): http://web.mit.edu/andersk/Public/api-hashmap/old-highlight.html Original version with syntax-highlight missing (corrupted): http://web.mit.edu/andersk/Public/api-hashmap/old-no-highlight.html Patched version (boring but readable): http://web.mit.edu/andersk/Public/api-hashmap/patched.html Anders -- 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
[PATCH] Documentation/technical/api-hashmap: Remove source highlighting
The highlighting was pretty, but unfortunately, the failure mode when source-highlight is not installed was that the entire code block disappears. See https://bugs.debian.org/745591, https://bugs.launchpad.net/bugs/1316810. Signed-off-by: Anders Kaseorg ande...@mit.edu --- Documentation/technical/api-hashmap.txt | 1 - 1 file changed, 1 deletion(-) diff --git a/Documentation/technical/api-hashmap.txt b/Documentation/technical/api-hashmap.txt index 42ca234..b977ae8 100644 --- a/Documentation/technical/api-hashmap.txt +++ b/Documentation/technical/api-hashmap.txt @@ -166,7 +166,6 @@ Usage example - Here's a simple usage example that maps long keys to double values. -[source,c] struct hashmap map; -- 2.0.0.rc3 -- 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] Documentation/technical/api-hashmap: Remove source highlighting
On Sat, May 17, 2014 at 07:08:55AM -0400, Anders Kaseorg wrote: The highlighting was pretty, but unfortunately, the failure mode when source-highlight is not installed was that the entire code block disappears. See https://bugs.debian.org/745591, https://bugs.launchpad.net/bugs/1316810. I agree that a broken document is an unacceptable failure mode. But I do not understand why 'source-highlight' is not an install requirement for 'git-doc'. If I install 'source-highlight' on my Debian machine the code looks great. apt-get install source-highlight I also noticed that this seems to be the single place where source code highlighting is used in Documentation/technical. So it might be worthwhile to eliminate this dependency all together as Anders patch does. -- Jeremiah Mahler jmmah...@gmail.com http://github.com/jmahler -- 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] Documentation/technical/api-hashmap: Remove source highlighting
On Sat, 17 May 2014, Jeremiah Mahler wrote: I agree that a broken document is an unacceptable failure mode. But I do not understand why 'source-highlight' is not an install requirement for 'git-doc'. If I install 'source-highlight' on my Debian machine the code looks great. apt-get install source-highlight Yes; when I noticed this failure, I asked Jonathan to add source-highlight as a build dependency in Debian (https://bugs.debian.org/745591). But then Ubuntu forked the packaging to revert this change (https://bugs.launchpad.net/bugs/1316810), because source-highlight in the community-supported universe repository is not allowed to be a build dependency of git in the Canonical-supported main repository. So now the Ubuntu package still has broken documentation _and_ it’s lost the ability to automatically synchronize updates from Debian. If we’re going to make Git depend on source-highlight, then we would want to make sure it’s documented in INSTALL and that its absence is properly diagnosed. Maybe then we could make the argument to Canonical that source-highlight should become officially supported in main (https://wiki.ubuntu.com/UbuntuMainInclusionRequirements). But I don’t that would be worth it just to make one page of the API documentation a little more colorful (and it sounds like you agree). Anders -- 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
