From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Jambunathan K Newsgroups: gmane.emacs.devel Subject: Re: Policy for documentation of ELPA Date: Sun, 17 Jul 2011 15:50:15 +0530 Message-ID: <81livx43a8.fsf@gmail.com> References: <87sjq9lvps.fsf@tochka.ru> <877h7h458x.fsf@tochka.ru> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: dough.gmane.org 1310898048 29432 80.91.229.12 (17 Jul 2011 10:20:48 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Sun, 17 Jul 2011 10:20:48 +0000 (UTC) Cc: emacs-devel@gnu.org To: "Evgeny M. Zubok" Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sun Jul 17 12:20:45 2011 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([140.186.70.17]) by lo.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1QiOSq-00020L-TD for ged-emacs-devel@m.gmane.org; Sun, 17 Jul 2011 12:20:45 +0200 Original-Received: from localhost ([::1]:33149 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QiOSq-00014F-47 for ged-emacs-devel@m.gmane.org; Sun, 17 Jul 2011 06:20:44 -0400 Original-Received: from eggs.gnu.org ([140.186.70.92]:37761) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QiOSc-00013h-NP for emacs-devel@gnu.org; Sun, 17 Jul 2011 06:20:31 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1QiOSb-0001cU-Gx for emacs-devel@gnu.org; Sun, 17 Jul 2011 06:20:30 -0400 Original-Received: from mail-pv0-f169.google.com ([74.125.83.169]:50600) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QiOSb-0001cP-9u for emacs-devel@gnu.org; Sun, 17 Jul 2011 06:20:29 -0400 Original-Received: by pvc12 with SMTP id 12so2748382pvc.0 for ; Sun, 17 Jul 2011 03:20:28 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma; h=from:to:cc:subject:references:mail-followup-to:date:in-reply-to :message-id:user-agent:mime-version:content-type; bh=oHZscd+SqqjsA/jHlPb8cJTSiwdb8QXKHDTehEeT5Cc=; b=HsJUg1oIXIdI4hYAQp0TvIDsqfJ6l0p6eyK7mPwq1naNmA4/7YeiRXN0hVt9sQYvjz fQto+XOQp8kB/6j+s7GzDNDDohoh8GYcD8y/kSQaGhQwfed9zGqjFhfrnn6ytv+ww38C vrKabMah44OsfDexoRYjDLs35Z1pcPSopfY/4= Original-Received: by 10.68.60.225 with SMTP id k1mr6982072pbr.443.1310898028425; Sun, 17 Jul 2011 03:20:28 -0700 (PDT) Original-Received: from JAMBU-NETBOOK ([115.241.55.247]) by mx.google.com with ESMTPS id b4sm1793117pba.91.2011.07.17.03.20.23 (version=TLSv1/SSLv3 cipher=OTHER); Sun, 17 Jul 2011 03:20:27 -0700 (PDT) Mail-Followup-To: "Evgeny M. Zubok" , emacs-devel@gnu.org In-Reply-To: <877h7h458x.fsf@tochka.ru> (Evgeny M. Zubok's message of "Sun, 17 Jul 2011 13:37:50 +0400") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.0.50 (windows-nt) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 2) X-Received-From: 74.125.83.169 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:142067 Archived-At: "Evgeny M. Zubok" writes: > Stefan Monnier writes: > >>> I have written documentation (an initial version) for one of the ELPA >>> package. The source is the texinfo file. I see that auctex provides the >>> documentation as exported .info file along with Postscript and PDF in >>> ./doc directory. Muse also provides the .info file. No package that >>> provides source of documentation (texinfo files, PostScript diagrams and >>> figures, etc). What is the current (if any) policy for documentation? >>> Should the package also contain sources, just in case if someone want to >>> improve the documentation? >> >> It should definitely contain the source (in this case the Texinfo) if at >> all possible. > > And what about the documentation in compiled format? org-mode and muse > have its own upstream development and they keep the documentation > sources there. The developers commit only user-readable documentation > into ELPA and they don't commit the texinfo. `debbugs' uses ELPA for > development. So, we have no other option than to store texinfo file in > ELPA. No problem. The main question is about the documentation in human > readable format. ELPA contains the files as they will be installed at > user side, right? Should I manually re-generate the final documentation > every time I have made even the little change in texinfo file? Can I do > it not very often? Where the documentation should arrive when the user > installs the ELPA package? I think you are suggesting that texi2pdf, texi2html be run on the texi files and pdftex be run on the tex cheatsheets if any, automagically by the ELPA infrastructure. Personally I think your suggestion is a very good idea and shifts the burden away from the developer. I think there is an opportuinity to further normalize the dir layout of elpa tarballs (for eg, maintainers could insist that all doc files go under ./doc etc etc) If you are talking of doc files that are NOT DERIVED from texi files then you can still include them under the directory of your own choosing in the resulting tarballs. ps: I am not much aware of the bzr version of GNU ELPA. Jambunathan K. --