From esr@thyrsus.com Thu Jan 11 13:03:44 2007 Return-Path: X-Original-To: gnome-doc-devel-list@gnome.org Delivered-To: gnome-doc-devel-list@gnome.org Received: from localhost (localhost.localdomain [127.0.0.1]) by menubar.gnome.org (Postfix) with ESMTP id 0DC173B035B for ; Thu, 11 Jan 2007 13:03:44 -0500 (EST) Received: from menubar.gnome.org ([127.0.0.1]) by localhost (menubar.gnome.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id 10723-09 for ; Thu, 11 Jan 2007 13:03:40 -0500 (EST) Received: from snark.thyrsus.com (static-71-162-243-5.phlapa.fios.verizon.net [71.162.243.5]) by menubar.gnome.org (Postfix) with ESMTP id 8A08E3B0096 for ; Thu, 11 Jan 2007 13:03:40 -0500 (EST) Received: from snark.thyrsus.com (localhost [127.0.0.1]) by snark.thyrsus.com (8.13.8/8.13.6) with ESMTP id l0BI3e91013753 for ; Thu, 11 Jan 2007 13:03:40 -0500 Received: (from esr@localhost) by snark.thyrsus.com (8.13.8/8.13.8/Submit) id l0BI3eox013752 for gnome-doc-devel-list@gnome.org; Thu, 11 Jan 2007 13:03:40 -0500 Date: Thu, 11 Jan 2007 13:03:40 -0500 From: "Eric S. Raymond" To: gnome-doc-devel-list@gnome.org Subject: Status of the yelp man-page parser Message-ID: <20070111180340.GA13689@thyrsus.com> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline User-Agent: Mutt/1.4.2.2i Organization: Eric Conspiracy Secret Labs X-Eric-Conspiracy: There is no conspiracy X-Virus-Scanned: by amavisd-new at gnome.org X-Spam-Status: No, score=-2.466 tagged_above=-999 required=2 tests=[BAYES_00=-2.599, FORGED_RCVD_HELO=0.135, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001] X-Spam-Score: -2.466 X-Spam-Level: X-Mailman-Approved-At: Thu, 11 Jan 2007 13:04:43 -0500 X-BeenThere: gnome-doc-devel-list@gnome.org X-Mailman-Version: 2.1.8 Precedence: list Reply-To: esr@thyrsus.com List-Id: "Discussion about development of yelp, gnome-doc-utils, and other documentation-related utilities" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 11 Jan 2007 18:03:44 -0000 I'm doing some work on the groff manual pages, trying to make sure they render correctly through various programs such as man2html, the KDE help broweser, manServer, and yelp. Towards that end, I recently had a look at the yelp source code at . My goal was to enumerate the sets of troff requests and escapes that it interprets. I left that page more puzzled than I arrived. It doesn't look to me like that code is functional -- in particular, it looks like .if conditionals and escapes in macro arguments aren't handled. And yet, yelp seems to be doing a pretty good job of displaying man pages that I know require these features. Have I missed something here, or is yelp actually doing something like calling groff behind the scenes? -- Eric S. Raymond From karderio@gmail.com Thu Jan 11 15:24:21 2007 Return-Path: X-Original-To: gnome-doc-devel-list@gnome.org Delivered-To: gnome-doc-devel-list@gnome.org Received: from localhost (localhost.localdomain [127.0.0.1]) by menubar.gnome.org (Postfix) with ESMTP id 2938D3B0476 for ; Thu, 11 Jan 2007 15:24:21 -0500 (EST) Received: from menubar.gnome.org ([127.0.0.1]) by localhost (menubar.gnome.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id 19282-03 for ; Thu, 11 Jan 2007 15:24:16 -0500 (EST) Received: from ug-out-1314.google.com (ug-out-1314.google.com [66.249.92.171]) by menubar.gnome.org (Postfix) with ESMTP id 948083B0450 for ; Thu, 11 Jan 2007 15:24:14 -0500 (EST) Received: by ug-out-1314.google.com with SMTP id 74so540977ugb for ; Thu, 11 Jan 2007 12:24:13 -0800 (PST) Received: by 10.66.216.1 with SMTP id o1mr2251086ugg.1168547053904; Thu, 11 Jan 2007 12:24:13 -0800 (PST) Received: from ?192.168.0.4? ( [83.179.154.59]) by mx.google.com with ESMTP id u6sm1335750uge.2007.01.11.12.24.06; Thu, 11 Jan 2007 12:24:12 -0800 (PST) Subject: Re: Help System Spec 0.2 From: karderio To: Cornelius Schumacher In-Reply-To: <200612271657.48921.schumacher@kde.org> References: <1164472768.5221.20.camel@Madaline> <200612271657.48921.schumacher@kde.org> Content-Type: text/plain Organization: karderio Date: Thu, 11 Jan 2007 21:23:54 +0100 Message-Id: <1168547034.31018.20.camel@localhost> Mime-Version: 1.0 X-Mailer: Evolution 2.8.1 Content-Transfer-Encoding: 7bit X-Virus-Scanned: by amavisd-new at gnome.org X-Spam-Status: No, score=-2.476 tagged_above=-999 required=2 tests=[AWL=0.124, BAYES_00=-2.599, SPF_PASS=-0.001] X-Spam-Score: -2.476 X-Spam-Level: Cc: xdg@lists.freedesktop.org, Doc Devel List X-BeenThere: gnome-doc-devel-list@gnome.org X-Mailman-Version: 2.1.8 Precedence: list Reply-To: karderio@gmail.com List-Id: "Discussion about development of yelp, gnome-doc-utils, and other documentation-related utilities" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 11 Jan 2007 20:24:21 -0000 Hi :o) I will try to answer some of your questions. On Wed, 2006-12-27 at 16:57 +0100, Cornelius Schumacher wrote: > On Saturday 25 November 2006 17:39, Don Scorgie wrote: > One question, though: Is D-Bus able to start the help browser on demand when a > call is made to the API or is it needed that the help browser is already > running (providing it is the help browser implementing the API)? Yes, I believe that Dbus will start Yelp on demand. > What about adding a call "open_browser", which would open the help browser > without showing a specific document, but with a generic start page? Maybe this could simply be achieved by sending the open_document signal with the "generic start page" DocIdentifier. > What's the use case for the close_document call? Wouldn't it be up to the user > to close the help window? Maybe it's a lack of my phantasy but I can't > imagine a situation where an application wanted to close a help window > programmatically. At first I couldn't see why either, but I think it could perhaps be useful in some weird and wonderful situations, I've tried to think up a couple here : I've seen some apps (on Windows, I think) close the help browser when you quit an app, not to say that is a good idea ;) Perhaps if for some reason an app was to open the help browser automatically (lets imagine to show important information on fist use of an app) it would want to close it at some point. > > * Remove the help: URI section. It causes confusion and is inextensible > > (installing a package in /opt with the docpath defined as help: > > would point to the wrong place) > > One purpose of the help: URIs is to specify a standard location for > documentation files. While it should be possible to install documentation to > other locations it still would be nice to have a standard location, so that > the location where files are installed is not completely arbitrary. To make a > separate spec for this purpose would probably be overkill, so I think it > would be nice to keep this in the help system spec. I think that even though a section about help: URIs was removed, the URIs are still permitted in the specification. (See the DocPath key part of the specification.) Hope this helps ! Love, Karderio. From schumacher@kde.org Wed Jan 17 05:40:50 2007 Return-Path: X-Original-To: gnome-doc-devel-list@gnome.org Delivered-To: gnome-doc-devel-list@gnome.org Received: from localhost (localhost.localdomain [127.0.0.1]) by menubar.gnome.org (Postfix) with ESMTP id 0987A3B0284 for ; Wed, 17 Jan 2007 05:40:50 -0500 (EST) X-Virus-Scanned: by amavisd-new at gnome.org X-Spam-Score: -2.586 X-Spam-Level: X-Spam-Status: No, score=-2.586 tagged_above=-999 required=2 tests=[AWL=0.013, BAYES_00=-2.599] X-Amavis-OS-Fingerprint: Linux 2.4-2.6 (up: 3059 hrs), (distance 17, link: ethernet/modem), [195.135.220.2] Received: from menubar.gnome.org ([127.0.0.1]) by localhost (menubar.gnome.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id ZVVpHYxk4XS4 for ; Wed, 17 Jan 2007 05:40:46 -0500 (EST) Received: from mx1.suse.de (mx1.suse.de [195.135.220.2]) by menubar.gnome.org (Postfix) with ESMTP id 730543B0190 for ; Wed, 17 Jan 2007 05:40:46 -0500 (EST) Received: from Relay2.suse.de (mail2.suse.de [195.135.221.8]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.suse.de (Postfix) with ESMTP id 3C1CA12068; Wed, 17 Jan 2007 11:40:40 +0100 (CET) From: Cornelius Schumacher To: xdg@lists.freedesktop.org Subject: Re: Help System Spec 0.2 Date: Wed, 17 Jan 2007 11:40:39 +0100 User-Agent: KMail/1.9.5 References: <1164472768.5221.20.camel@Madaline> <200612271657.48921.schumacher@kde.org> <1168547034.31018.20.camel@localhost> In-Reply-To: <1168547034.31018.20.camel@localhost> MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: 7bit Content-Disposition: inline Message-Id: <200701171140.39517.schumacher@kde.org> Cc: Doc Devel List X-BeenThere: gnome-doc-devel-list@gnome.org X-Mailman-Version: 2.1.8 Precedence: list List-Id: "Discussion about development of yelp, gnome-doc-utils, and other documentation-related utilities" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 17 Jan 2007 10:40:50 -0000 On Thursday 11 January 2007 21:23, karderio wrote: > On Wed, 2006-12-27 at 16:57 +0100, Cornelius Schumacher wrote: > > On Saturday 25 November 2006 17:39, Don Scorgie wrote: > > > > * Remove the help: URI section. It causes confusion and is > > > inextensible (installing a package in /opt with the docpath defined as > > > help: would point to the wrong place) > > > > One purpose of the help: URIs is to specify a standard location for > > documentation files. While it should be possible to install documentation > > to other locations it still would be nice to have a standard location, so > > that the location where files are installed is not completely arbitrary. > > To make a separate spec for this purpose would probably be overkill, so I > > think it would be nice to keep this in the help system spec. > > I think that even though a section about help: URIs was removed, the > URIs are still permitted in the specification. (See the DocPath key part > of the specification.) The important point is to have the meaning of the URIs specified. Only permitting them in the specs doesn't solve the problem where help files are supposed to be installed. -- Cornelius Schumacher From esr@thyrsus.com Thu Jan 11 13:03:44 2007 Return-Path: X-Original-To: gnome-doc-devel-list@gnome.org Delivered-To: gnome-doc-devel-list@gnome.org Received: from localhost (localhost.localdomain [127.0.0.1]) by menubar.gnome.org (Postfix) with ESMTP id 0DC173B035B for ; Thu, 11 Jan 2007 13:03:44 -0500 (EST) Received: from menubar.gnome.org ([127.0.0.1]) by localhost (menubar.gnome.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id 10723-09 for ; Thu, 11 Jan 2007 13:03:40 -0500 (EST) Received: from snark.thyrsus.com (static-71-162-243-5.phlapa.fios.verizon.net [71.162.243.5]) by menubar.gnome.org (Postfix) with ESMTP id 8A08E3B0096 for ; Thu, 11 Jan 2007 13:03:40 -0500 (EST) Received: from snark.thyrsus.com (localhost [127.0.0.1]) by snark.thyrsus.com (8.13.8/8.13.6) with ESMTP id l0BI3e91013753 for ; Thu, 11 Jan 2007 13:03:40 -0500 Received: (from esr@localhost) by snark.thyrsus.com (8.13.8/8.13.8/Submit) id l0BI3eox013752 for gnome-doc-devel-list@gnome.org; Thu, 11 Jan 2007 13:03:40 -0500 Date: Thu, 11 Jan 2007 13:03:40 -0500 From: "Eric S. Raymond" To: gnome-doc-devel-list@gnome.org Subject: Status of the yelp man-page parser Message-ID: <20070111180340.GA13689@thyrsus.com> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline User-Agent: Mutt/1.4.2.2i Organization: Eric Conspiracy Secret Labs X-Eric-Conspiracy: There is no conspiracy X-Virus-Scanned: by amavisd-new at gnome.org X-Spam-Status: No, score=-2.466 tagged_above=-999 required=2 tests=[BAYES_00=-2.599, FORGED_RCVD_HELO=0.135, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001] X-Spam-Score: -2.466 X-Spam-Level: X-Mailman-Approved-At: Thu, 11 Jan 2007 13:04:43 -0500 X-BeenThere: gnome-doc-devel-list@gnome.org X-Mailman-Version: 2.1.8 Precedence: list Reply-To: esr@thyrsus.com List-Id: "Discussion about development of yelp, gnome-doc-utils, and other documentation-related utilities" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 11 Jan 2007 18:03:44 -0000 I'm doing some work on the groff manual pages, trying to make sure they render correctly through various programs such as man2html, the KDE help broweser, manServer, and yelp. Towards that end, I recently had a look at the yelp source code at . My goal was to enumerate the sets of troff requests and escapes that it interprets. I left that page more puzzled than I arrived. It doesn't look to me like that code is functional -- in particular, it looks like .if conditionals and escapes in macro arguments aren't handled. And yet, yelp seems to be doing a pretty good job of displaying man pages that I know require these features. Have I missed something here, or is yelp actually doing something like calling groff behind the scenes? -- Eric S. Raymond From karderio@gmail.com Thu Jan 11 15:24:21 2007 Return-Path: X-Original-To: gnome-doc-devel-list@gnome.org Delivered-To: gnome-doc-devel-list@gnome.org Received: from localhost (localhost.localdomain [127.0.0.1]) by menubar.gnome.org (Postfix) with ESMTP id 2938D3B0476 for ; Thu, 11 Jan 2007 15:24:21 -0500 (EST) Received: from menubar.gnome.org ([127.0.0.1]) by localhost (menubar.gnome.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id 19282-03 for ; Thu, 11 Jan 2007 15:24:16 -0500 (EST) Received: from ug-out-1314.google.com (ug-out-1314.google.com [66.249.92.171]) by menubar.gnome.org (Postfix) with ESMTP id 948083B0450 for ; Thu, 11 Jan 2007 15:24:14 -0500 (EST) Received: by ug-out-1314.google.com with SMTP id 74so540977ugb for ; Thu, 11 Jan 2007 12:24:13 -0800 (PST) Received: by 10.66.216.1 with SMTP id o1mr2251086ugg.1168547053904; Thu, 11 Jan 2007 12:24:13 -0800 (PST) Received: from ?192.168.0.4? ( [83.179.154.59]) by mx.google.com with ESMTP id u6sm1335750uge.2007.01.11.12.24.06; Thu, 11 Jan 2007 12:24:12 -0800 (PST) Subject: Re: Help System Spec 0.2 From: karderio To: Cornelius Schumacher In-Reply-To: <200612271657.48921.schumacher@kde.org> References: <1164472768.5221.20.camel@Madaline> <200612271657.48921.schumacher@kde.org> Content-Type: text/plain Organization: karderio Date: Thu, 11 Jan 2007 21:23:54 +0100 Message-Id: <1168547034.31018.20.camel@localhost> Mime-Version: 1.0 X-Mailer: Evolution 2.8.1 Content-Transfer-Encoding: 7bit X-Virus-Scanned: by amavisd-new at gnome.org X-Spam-Status: No, score=-2.476 tagged_above=-999 required=2 tests=[AWL=0.124, BAYES_00=-2.599, SPF_PASS=-0.001] X-Spam-Score: -2.476 X-Spam-Level: Cc: xdg@lists.freedesktop.org, Doc Devel List X-BeenThere: gnome-doc-devel-list@gnome.org X-Mailman-Version: 2.1.8 Precedence: list Reply-To: karderio@gmail.com List-Id: "Discussion about development of yelp, gnome-doc-utils, and other documentation-related utilities" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 11 Jan 2007 20:24:21 -0000 Hi :o) I will try to answer some of your questions. On Wed, 2006-12-27 at 16:57 +0100, Cornelius Schumacher wrote: > On Saturday 25 November 2006 17:39, Don Scorgie wrote: > One question, though: Is D-Bus able to start the help browser on demand when a > call is made to the API or is it needed that the help browser is already > running (providing it is the help browser implementing the API)? Yes, I believe that Dbus will start Yelp on demand. > What about adding a call "open_browser", which would open the help browser > without showing a specific document, but with a generic start page? Maybe this could simply be achieved by sending the open_document signal with the "generic start page" DocIdentifier. > What's the use case for the close_document call? Wouldn't it be up to the user > to close the help window? Maybe it's a lack of my phantasy but I can't > imagine a situation where an application wanted to close a help window > programmatically. At first I couldn't see why either, but I think it could perhaps be useful in some weird and wonderful situations, I've tried to think up a couple here : I've seen some apps (on Windows, I think) close the help browser when you quit an app, not to say that is a good idea ;) Perhaps if for some reason an app was to open the help browser automatically (lets imagine to show important information on fist use of an app) it would want to close it at some point. > > * Remove the help: URI section. It causes confusion and is inextensible > > (installing a package in /opt with the docpath defined as help: > > would point to the wrong place) > > One purpose of the help: URIs is to specify a standard location for > documentation files. While it should be possible to install documentation to > other locations it still would be nice to have a standard location, so that > the location where files are installed is not completely arbitrary. To make a > separate spec for this purpose would probably be overkill, so I think it > would be nice to keep this in the help system spec. I think that even though a section about help: URIs was removed, the URIs are still permitted in the specification. (See the DocPath key part of the specification.) Hope this helps ! Love, Karderio. From schumacher@kde.org Wed Jan 17 05:40:50 2007 Return-Path: X-Original-To: gnome-doc-devel-list@gnome.org Delivered-To: gnome-doc-devel-list@gnome.org Received: from localhost (localhost.localdomain [127.0.0.1]) by menubar.gnome.org (Postfix) with ESMTP id 0987A3B0284 for ; Wed, 17 Jan 2007 05:40:50 -0500 (EST) X-Virus-Scanned: by amavisd-new at gnome.org X-Spam-Score: -2.586 X-Spam-Level: X-Spam-Status: No, score=-2.586 tagged_above=-999 required=2 tests=[AWL=0.013, BAYES_00=-2.599] X-Amavis-OS-Fingerprint: Linux 2.4-2.6 (up: 3059 hrs), (distance 17, link: ethernet/modem), [195.135.220.2] Received: from menubar.gnome.org ([127.0.0.1]) by localhost (menubar.gnome.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id ZVVpHYxk4XS4 for ; Wed, 17 Jan 2007 05:40:46 -0500 (EST) Received: from mx1.suse.de (mx1.suse.de [195.135.220.2]) by menubar.gnome.org (Postfix) with ESMTP id 730543B0190 for ; Wed, 17 Jan 2007 05:40:46 -0500 (EST) Received: from Relay2.suse.de (mail2.suse.de [195.135.221.8]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.suse.de (Postfix) with ESMTP id 3C1CA12068; Wed, 17 Jan 2007 11:40:40 +0100 (CET) From: Cornelius Schumacher To: xdg@lists.freedesktop.org Subject: Re: Help System Spec 0.2 Date: Wed, 17 Jan 2007 11:40:39 +0100 User-Agent: KMail/1.9.5 References: <1164472768.5221.20.camel@Madaline> <200612271657.48921.schumacher@kde.org> <1168547034.31018.20.camel@localhost> In-Reply-To: <1168547034.31018.20.camel@localhost> MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: 7bit Content-Disposition: inline Message-Id: <200701171140.39517.schumacher@kde.org> Cc: Doc Devel List X-BeenThere: gnome-doc-devel-list@gnome.org X-Mailman-Version: 2.1.8 Precedence: list List-Id: "Discussion about development of yelp, gnome-doc-utils, and other documentation-related utilities" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 17 Jan 2007 10:40:50 -0000 On Thursday 11 January 2007 21:23, karderio wrote: > On Wed, 2006-12-27 at 16:57 +0100, Cornelius Schumacher wrote: > > On Saturday 25 November 2006 17:39, Don Scorgie wrote: > > > > * Remove the help: URI section. It causes confusion and is > > > inextensible (installing a package in /opt with the docpath defined as > > > help: would point to the wrong place) > > > > One purpose of the help: URIs is to specify a standard location for > > documentation files. While it should be possible to install documentation > > to other locations it still would be nice to have a standard location, so > > that the location where files are installed is not completely arbitrary. > > To make a separate spec for this purpose would probably be overkill, so I > > think it would be nice to keep this in the help system spec. > > I think that even though a section about help: URIs was removed, the > URIs are still permitted in the specification. (See the DocPath key part > of the specification.) The important point is to have the meaning of the URIs specified. Only permitting them in the specs doesn't solve the problem where help files are supposed to be installed. -- Cornelius Schumacher