From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp12.migadu.com ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms9.migadu.com with LMTPS id kBbaCw+OnGS1ngAASxT56A (envelope-from ) for ; Wed, 28 Jun 2023 21:46:23 +0200 Received: from aspmx1.migadu.com ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp12.migadu.com with LMTPS id eBCyCw+OnGSFQwAAauVa8A (envelope-from ) for ; Wed, 28 Jun 2023 21:46:23 +0200 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id C233A19E82 for ; Wed, 28 Jun 2023 21:46:22 +0200 (CEST) Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=excalamus.com header.s=zmail header.b=MAmoQ6ek; dmarc=none; spf=pass (aspmx1.migadu.com: domain of "emacs-orgmode-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="emacs-orgmode-bounces+larch=yhetil.org@gnu.org"; arc=pass ("zohomail.com:s=zohoarc:i=1") ARC-Seal: i=2; s=key1; d=yhetil.org; t=1687981582; a=rsa-sha256; cv=pass; b=Gi1Y4Kv3DiCyTi8hKw1sFjAShZ9BrGr0W4fAGy49CnYeL8eIqM6gFhumssc66+mg7BnMtR zaVA77b8Xf2WTvHhosi3gkGw1xYG+39dvhBMMnYtjpTRoJSGueU4GQbhQkkc9s5lHBXFXw tV5wv29trB3EMOHsgJHjpOD9loEd/vTSoyA9RIyEF6hjIqFk0L1ID2To3djopNtRM3Ixc7 gabe6HXPsuZcbIyFCma7Jhwp6t3MuPhU0yY4OJzxQ9ssk9hhoWFwGncsNn9ntnkRdUUFS8 qV9Gp1lqjIP6j3wt8Dg6bXSthxiVRAf73qI1DkuDqlnZ/itmff0XLiy1JGlpUQ== ARC-Authentication-Results: i=2; aspmx1.migadu.com; dkim=pass header.d=excalamus.com header.s=zmail header.b=MAmoQ6ek; dmarc=none; spf=pass (aspmx1.migadu.com: domain of "emacs-orgmode-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="emacs-orgmode-bounces+larch=yhetil.org@gnu.org"; arc=pass ("zohomail.com:s=zohoarc:i=1") ARC-Message-Signature: i=2; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1687981582; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type:in-reply-to:in-reply-to:list-id:list-help: list-unsubscribe:list-subscribe:list-post:dkim-signature; bh=TM6gYM0Q/gDuSQx4AsmT1rH+5oQQQipK3v3QIYJD7Gg=; b=EgLHmR2RJIVOkZ84697V5QxZGeUF5ylIbpQ0qLSgddPTQAdVN5OUuLhud5XNJaT9wJL5BH WvfoosbVjTC7kIa1G+nHyssLx8b+HN6D0KxA8RmWsP4RZGXtzz6HYjjMVSVeedi6jEwBb0 E4PfC/mPjck7jAj3oIOeYwKq2DZxmgOHTnLyQ3w4tT2sJuPor3lk2gzYKBe1jlENUuIiue ucK4ebLu6/xR9wWJNVKWhXXgct4rq0/PBXBheAWF9/RhjrFlPGOl+j7MWXhj/+wWWNMAHE mocV40Yzbfc00pi/RLAxxZHjD3LmCfaqDHU9QXaVnbnzIJnKqIhOqvxNCrHmwg== Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qEb6R-0002mH-H0; Wed, 28 Jun 2023 15:45:23 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qEb6N-0002lu-Fs for emacs-orgmode@gnu.org; Wed, 28 Jun 2023 15:45:19 -0400 Received: from sender4-op-o15.zoho.com ([136.143.188.15]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qEb6L-0003Ch-Af for emacs-orgmode@gnu.org; Wed, 28 Jun 2023 15:45:18 -0400 ARC-Seal: i=1; a=rsa-sha256; t=1687981509; cv=none; d=zohomail.com; s=zohoarc; b=mStLDMFWLR8qDslHuTguMbnX0rQmGPUwG6Fv1zIiugJAxaEVJQI24vPrfq1nBvNCdvZ3LM2vOhLEeMoHbs9adhEfv2b5XUgeuSYHhPOYPRM5g4yCl4p2iAfD552GUp4gVKbNEuvL+Kj1qnQWeFl2akNZJsUqmspdeduFAIsZOW0= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1687981509; h=Content-Type:Date:From:MIME-Version:Message-ID:Subject:To; bh=TM6gYM0Q/gDuSQx4AsmT1rH+5oQQQipK3v3QIYJD7Gg=; b=FS46frt7JGra9/6mQuuQIXmeizE9W6lZ+yBg4CAMGKBgRzSGWKux0PieNmqoW7ps010DadbDSBfzNcYrR4kV5mXXVdlK6/UKUO/ylPIY+CowhOgRrTvfns2w469XGxWPar/rMI4C3wc1du74FwllPkRN8aVZJBJAhGf7ZcGDHIw= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass header.i=excalamus.com; spf=pass smtp.mailfrom=matt@excalamus.com; dmarc=pass header.from= DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; t=1687981509; s=zmail; d=excalamus.com; i=matt@excalamus.com; h=Date:Date:From:From:To:To:Message-Id:Message-Id:In-Reply-To:Subject:Subject:MIME-Version:Content-Type:Reply-To:Cc; bh=TM6gYM0Q/gDuSQx4AsmT1rH+5oQQQipK3v3QIYJD7Gg=; b=MAmoQ6ek4BvOApbrm3o8qSso3S45wodGXt7nnR5B8vdsOjuq75ZmjpCbAZogoMk8 Hr3eU4mH05+L4mxJH0rlZ/ZZlyu6SF0vhxtrLPe5p5s0PGAfYzJuXarRCOFkNa0fph7 XQB1Po72LG26P4/l5JPaOfZe7BqdfTu1JiXuemPY= Received: from mail.zoho.com by mx.zohomail.com with SMTP id 1687981509013397.0409889664469; Wed, 28 Jun 2023 12:45:09 -0700 (PDT) Date: Wed, 28 Jun 2023 21:45:08 +0200 From: Matt To: "emacs-orgmode" Message-Id: <1890389c8ff.c8d13885752260.8791711332615822478@excalamus.com> In-Reply-To: Subject: Export Documentation Confusions MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="----=_Part_2580786_516456673.1687981508863" Importance: Medium User-Agent: Zoho Mail X-Mailer: Zoho Mail X-Zoho-Virus-Status: 1 Received-SPF: pass client-ip=136.143.188.15; envelope-from=matt@excalamus.com; helo=sender4-op-o15.zoho.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H3=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-orgmode@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+larch=yhetil.org@gnu.org Sender: emacs-orgmode-bounces+larch=yhetil.org@gnu.org X-Migadu-Country: US X-Migadu-Flow: FLOW_IN X-Migadu-Scanner: scn1.migadu.com X-Migadu-Spam-Score: -4.74 X-Migadu-Queue-Id: C233A19E82 X-Spam-Score: -4.74 X-TUID: AXDFRmUbNm1I ------=_Part_2580786_516456673.1687981508863 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable In the Emacs Berlin meeting today, we noticed several items that might be i= mproved in the manual. - Section 13.18. 1: Bare HTML may be better placed under Section 13.9 HTML = Export. The information in this section appears unrelated to Exporting in = non-Org buffers. In fact, the settings given for a minimal HTML export do= not apply when converting a region. For example, when converting a region= containing an Org table to HTML, a preamble is not inserted even when the = variable `org-html-preamble` is t. https://orgmode.org/manual/Bare-HTML.html Proposed solution: Move Section 13.18.1 nearer the sections on HTML export. - Section 13.18: Export in Foreign Buffers The section uses the term "foreign buffer" without providing a definition. = It appears to mean a buffer without "org-mode" enabled. The section descr= ibes functions which allow users to write Org mode syntax in non-Org buffer= s and use various functions to convert the Org syntax to other syntaxes, li= ke HTML, Markdown, etc. https://orgmode.org/manual/Export-in-Foreign-Buffers.html Proposed solution: Change wording from "foreign buffers" to "Convert Region= " and "non-Org" buffer. The functionality is really about conversion rath= er than anything to do with non-Org buffers. If fact, Org respects users' = freedom to run the program as they wish=E2=80=93it does not prevent them fr= om converting Org formatted text within an Org buffer to a non-Org format, = no matter how absurd it may appear :) - Section 13.18: Export in Foreign Buffers There was confusion caused by the function names. Specifically, the "names= pace" (such as "org-ascii-" or "org-texinfo-") is confusing to users who ar= e not familiar with Org function naming conventions. For example, one parti= cipant thought `org-ascii-convert-region-to-utf8` might convert non-utf8 as= cii to utf8 and was confused why `org-texinfo-convert-region-to-texinfo` wo= uld convert texinfo to texinfo. Of course, this is not a correct understan= ding of the function behavior. https://orgmode.org/manual/Export-in-Foreign-Buffers.html Proposed solution: Clarify the overall purpose of the functions. Another s= olution could be to make an aside and clarify what is meant by "Org export = back end". For example, change "The export back-ends in Org often include..." to=20 "The export back-ends in Org (for example, Org ASCII or Org HTML) often inc= lude..." However, my hope is that the changes I made with regard to "foreign buffers= " also clarifies the purpose and use of functions listed in this section. These changes are given in the attached patches. If there are no suggeste= d improvements, I could merge them in. Please let me know your thoughts. ------=_Part_2580786_516456673.1687981508863 Content-Type: application/octet-stream; name=move-bare-html-section-to-html-export-section.patch Content-Transfer-Encoding: 7bit X-ZM_AttachId: 139072743088640350 Content-Disposition: attachment; filename=move-bare-html-section-to-html-export-section.patch diff --git a/doc/org-manual.org b/doc/org-manual.org index 76131f110..c47971914 100644 --- a/doc/org-manual.org +++ b/doc/org-manual.org @@ -13213,6 +13213,32 @@ a postamble from looking up author's name, email address, creator's name, and date. +*** Exporting to minimal HTML +:PROPERTIES: +:DESCRIPTION: Exporting HTML without CSS, Javascript, etc. +:ALT_TITLE: Bare HTML +:END: + +If you want to output a minimal HTML file, with no CSS, no Javascript, +no preamble or postamble, here are the variable you would need to set: + +#+vindex: org-html-head +#+vindex: org-html-head-extra +#+vindex: org-html-head-include-default-style +#+vindex: org-html-head-include-scripts +#+vindex: org-html-preamble +#+vindex: org-html-postamble +#+vindex: org-html-use-infojs +#+begin_src emacs-lisp +(setq org-html-head "" + org-html-head-extra "" + org-html-head-include-default-style nil + org-html-head-include-scripts nil + org-html-preamble nil + org-html-postamble nil + org-html-use-infojs nil) +#+end_src + *** Quoting HTML tags :PROPERTIES: :DESCRIPTION: Using direct HTML in Org files. @@ -16410,32 +16436,6 @@ tables and lists in foreign buffers. For example, in an HTML buffer, write a list in Org syntax, select it, and convert it to HTML with {{{kbd(M-x org-html-convert-region-to-html)}}}. -*** Exporting to minimal HTML -:PROPERTIES: -:DESCRIPTION: Exporting HTML without CSS, Javascript, etc. -:ALT_TITLE: Bare HTML -:END: - -If you want to output a minimal HTML file, with no CSS, no Javascript, -no preamble or postamble, here are the variable you would need to set: - -#+vindex: org-html-head -#+vindex: org-html-head-extra -#+vindex: org-html-head-include-default-style -#+vindex: org-html-head-include-scripts -#+vindex: org-html-preamble -#+vindex: org-html-postamble -#+vindex: org-html-use-infojs -#+begin_src emacs-lisp -(setq org-html-head "" - org-html-head-extra "" - org-html-head-include-default-style nil - org-html-head-include-scripts nil - org-html-preamble nil - org-html-postamble nil - org-html-use-infojs nil) -#+end_src - * Publishing :PROPERTIES: :DESCRIPTION: Create a web site of linked Org files. ------=_Part_2580786_516456673.1687981508863 Content-Type: application/octet-stream; name=change-foreign-to-non-org.patch Content-Transfer-Encoding: 7bit X-ZM_AttachId: 139072743088780150 Content-Disposition: attachment; filename=change-foreign-to-non-org.patch diff --git a/doc/org-manual.org b/doc/org-manual.org index 76131f110..b0dbe4ec6 100644 --- a/doc/org-manual.org +++ b/doc/org-manual.org @@ -16365,15 +16365,14 @@ Further steps to consider would be an interactive function, self-installing an item in the export dispatcher menu, and other user-friendly improvements. -** Export in Foreign Buffers +** Convert Region :PROPERTIES: :DESCRIPTION: Author tables and lists in Org syntax. :END: -The export backends in Org often include commands to convert selected -regions. A convenient feature of this in-place conversion is that the -exported output replaces the original source. Here are such -functions: +Some export backends include commands to convert a region of Org +formatted text to another format, such as HTML or LaTeX. The +conversion replaces the original source. Here are such functions: - ~org-ascii-convert-region-to-ascii~ :: @@ -16405,8 +16404,8 @@ functions: #+findex: org-md-convert-region-to-md Convert the selected region into Markdown. -In-place conversions are particularly handy for quick conversion of -tables and lists in foreign buffers. For example, in an HTML buffer, +The in-place conversion is particularly handy for quick conversion of +tables and lists in non-Org buffers. For example, in an HTML buffer, write a list in Org syntax, select it, and convert it to HTML with {{{kbd(M-x org-html-convert-region-to-html)}}}. ------=_Part_2580786_516456673.1687981508863--