From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp2 ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms11 with LMTPS id QN2BAe0NU1+PGQAA0tVLHw (envelope-from ) for ; Sat, 05 Sep 2020 04:02:53 +0000 Received: from aspmx1.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp2 with LMTPS id 2GYKOewNU1+6CgAAB5/wlQ (envelope-from ) for ; Sat, 05 Sep 2020 04:02:52 +0000 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 4CE359402CB for ; Sat, 5 Sep 2020 04:02:52 +0000 (UTC) Received: from localhost ([::1]:58078 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kEPPe-0004OU-VE for larch@yhetil.org; Sat, 05 Sep 2020 00:02:50 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:33706) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kEPP6-0004O8-Io for emacs-orgmode@gnu.org; Sat, 05 Sep 2020 00:02:16 -0400 Received: from mail-pj1-x102b.google.com ([2607:f8b0:4864:20::102b]:51648) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1kEPP4-00067O-7J for emacs-orgmode@gnu.org; Sat, 05 Sep 2020 00:02:16 -0400 Received: by mail-pj1-x102b.google.com with SMTP id a9so881675pjg.1 for ; Fri, 04 Sep 2020 21:02:13 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:subject:in-reply-to:references:date:message-id:mime-version :content-transfer-encoding; bh=dm918c/ULqr0RB5fPSBbLlmXfVb1rHSC1Xc+0EX5SM8=; b=o9x7nWWores2hJMkPg2+sGfZ1QJjrwABk/7oN1c8Muf6WPDlgUFWwMiQft74nTrMjc GOJjUoSZq+EiDZBGesCYrFwQ8RIplPnwdS5+OExh83yeqR8bD8Sc3eQumA8HJtGpihcU I4dL3KiVW0RkRXgy5yZ6xyiVsiDknbUqcD1dCIqPMBEUbjdrst9XG9x67eC16fdUNHEv OcMn8HBbKZv/0MwpvnSNswK11enzlsiRxroufU4vZGZS6pdBV6KofdpZUsy0JoLWJQJQ ZkWxLOVyPz7vFavipFqkz2UuQl015UtjZ4Nc9CVZ6hpX6NpunHk18ksKIpMcEZum4SS/ CgJw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:subject:in-reply-to:references:date :message-id:mime-version:content-transfer-encoding; bh=dm918c/ULqr0RB5fPSBbLlmXfVb1rHSC1Xc+0EX5SM8=; b=ap+Xxi1JGCJX2Fq3nF7xclReIyoOP9R4u49kJOCq4+SGvj1SwFr3UloNdVcnwtzMOu AAB/NMDTKwhPmp/mu1h3Vq6FxzeN01V+DUSCv+eVrCUMIpOG/OIpNwMyP+ZsGVqBHJkZ Ziw48x+vTIZJuVlsCSOPXKwjeIjE1ZSWjLQAXUctnKahRSIeXGXIWYcygc12aXsjTDgY /wtnfn46SsHf+NsK9nAaNlej5iqlTvDwhc5D3d5dZQmyyF0Id6L+D4s1TwGTkwOefYTz /+Zottd//GbyOKvNBBj8PfKymEtqk2BEGcJmmyJNWAgWNnDBFqBzYJh9WvR4r1UvYQs4 F6uw== X-Gm-Message-State: AOAM530Po9ac4xszQIKA7odSbwmHEQiIFX+nTxoYiL5jFMtOCjN7X+ad CkiVjEi7XpzLwfQRkNmicYtnjJu0d7ScFQ== X-Google-Smtp-Source: ABdhPJxbwfED38VnfQToVgZrniZgNbviqe9HdCSMvb/S+gyEL4cHFbI4jTChGFKOctBTqtHDpcK3cg== X-Received: by 2002:a17:90b:4b89:: with SMTP id lr9mr11507566pjb.190.1599278531941; Fri, 04 Sep 2020 21:02:11 -0700 (PDT) Received: from localhost ([66.212.20.8]) by smtp.gmail.com with ESMTPSA id q24sm8011295pfs.206.2020.09.04.21.02.09 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 04 Sep 2020 21:02:11 -0700 (PDT) From: Ihor Radchenko To: hj-orgmode-1@hj.proberto.com, emacs-orgmode@gnu.org Subject: Re: documentation feature: typical .org files as starting points along with screencasts In-Reply-To: References: Date: Sat, 05 Sep 2020 12:01:11 +0800 Message-ID: <877dt8an3s.fsf@localhost> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Received-SPF: pass client-ip=2607:f8b0:4864:20::102b; envelope-from=yantar92@gmail.com; helo=mail-pj1-x102b.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. X-Spam_score_int: -17 X-Spam_score: -1.8 X-Spam_bar: - X-Spam_report: (-1.8 / 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, FREEMAIL_ENVFROM_END_DIGIT=0.25, FREEMAIL_FROM=0.001, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-orgmode@gnu.org X-Mailman-Version: 2.1.23 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" X-Scanner: scn0 Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20161025 header.b=o9x7nWWo; dmarc=pass (policy=none) header.from=gmail.com; spf=pass (aspmx1.migadu.com: domain of emacs-orgmode-bounces@gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=emacs-orgmode-bounces@gnu.org X-Spam-Score: -1.21 X-TUID: A5Hh/NnZmcn/ > =C2=A0Hello, Welcome to org community ;) > =C2=A0 I would find it tremendously useful if, perhaps as a part of the= =20 > documentation, there were several sample .org files, at various levels=20 > of complexity (features used) _along_ _with_ a quick and simple screen=20 > cast of its features being used in a real-life scenario. ( I find it=20 > most useful for such screen casts to display key presses as they occur=20 > ... is there a "plugin" which would 1) show the keys being pressed and=20 > 2) also show the resulting functions being invoked by those keystrokes?=20 > ). You may find the tutorial section org org-mode wiki useful: https://orgmode.org/worg/org-tutorials/index.html Not all, but some of the video tutorials there also contain a github repo with reference configuration or org files. > =C2=A0It seems to me that to get people started without unnecessary=20 > frustrations, we might want to put into the docs something like: > > To include feature : timestamp-based unique IDs : Configure emacs thusly= =20 > : insertion> and then see how this works ; ...=C2=A0 same for= =20 > features like=C2=A0 HTML export, literal programming, custom timestamp=20 > (perhaps with down-to-seconds resolution) custom, etc It may be more practical to link the relevant wiki sections from the org manual itself. Then, we can formalise wiki article formats to include videos, configuration, and org examples. > Repeatedly I've spent more than an hour trying to figure out what=20 > happened when I haven't noticed that by mistake that I've pressed some=20 > weird key combo which has placed my orgmode/emacs session in an=20 > incomprehensible state - e.g. narrowing a buffer. Fair point. Narrowing functionality is disabled in Emacs by default and shows a warning when a user tries to execute narrowing commands. However, this is not the case for narrow-related org-mode functions. We should probably disable the narrow commands via (put 'function 'disabled t) Then, news users will at least be warned that command may create a confusion. > Had I known which keys=20 > I had pressed by mistake, or at least the functions that they involved,=20 > I could have looked up the manual to see how to "undo" such mess. But=20 > when you don't know that your state is being called "narrowing buffer",=20 > you have no clue what just happened and that you should find out how to=20 > "widen" it again. ( That is very, VERY frustrating for an emacs/orgmode=20 > newbie. Someone please advise how to turn on a log of keystrokes and=20 > functions being invoked by those keystrokes. ... Consider having this on= =20 > as default for newbies. ) For future, you can always execute M-x view-lossage to see the keystrokes you pressed earlier and the functions called by those keystrokes. This command is a part of Emacs itself. > =C2=A0I believe if I saw in a few screen casts how the orgmode=20 > "professionals" use orgmode, and had access to their sample orgmode=20 > files which I could follow along and literally identically modify during= =20 > the screencast, I would be much father (and perhaps even happier) with=20 > the use of orgmode. I think the most crucial point for newbies is being=20 > able to literally follow the screencast along, perfectly replicating the= =20 > screen cast results in their emacs / evil / spacemacs setup. > If people would want to send me URLs for their sample .org files for=20 > which they also have a demo screen cast on how to use their features, I=20 > would like to pull these together and create a section for the docs with= =20 > these. Creating a screencast or even example .org file is not trivial - we cannot just share own personal .org files in public in majority of cases. A good screencast should also not rely on the other parts of personal configuration. The problem is that personal config tends to get very, *very* large for long-time users (and we are so used to it that it is easy to forget that something is actually not default setting). A simple example: I am using personalised (different from vim) modal editing with non-standard key bindings - recorded keystrokes would not help a new user at all. Also, it is not clear what features are worth sharing. If you are willing to invest your time in creating the docs/worg pages, you may probably create a list of features you think are good to be documented and then request volunteers to create screencasts (maybe also contact the existing video creators making Emacs videos) along with example org files (using their personal config). Then, it will be necessary to make sure that the screencasts can actually be reproduced from default org-mode settings. If you are willing to do it (and if you will be granted edit rights to worg), I can probably help you with initial screencasts during my spare time.=20 Best, Ihor hj-orgmode-1@hj.proberto.com writes: > =C2=A0Hello, > > =C2=A0First of all, orgmode rocks! > > =C2=A0 I am trying to work with with orgmode=C2=A0 for a few months now,= and I=20 > feel like I am still only scratching the surface. I've read the manual,=20 > and the online docs, yet fully functional access to some features eludes= =20 > me still. > > =C2=A0 I would find it tremendously useful if, perhaps as a part of the= =20 > documentation, there were several sample .org files, at various levels=20 > of complexity (features used) _along_ _with_ a quick and simple screen=20 > cast of its features being used in a real-life scenario. ( I find it=20 > most useful for such screen casts to display key presses as they occur=20 > ... is there a "plugin" which would 1) show the keys being pressed and=20 > 2) also show the resulting functions being invoked by those keystrokes?=20 > ). Repeatedly I've spent more than an hour trying to figure out what=20 > happened when I haven't noticed that by mistake that I've pressed some=20 > weird key combo which has placed my orgmode/emacs session in an=20 > incomprehensible state - e.g. narrowing a buffer. Had I known which keys= =20 > I had pressed by mistake, or at least the functions that they involved,=20 > I could have looked up the manual to see how to "undo" such mess. But=20 > when you don't know that your state is being called "narrowing buffer",=20 > you have no clue what just happened and that you should find out how to=20 > "widen" it again. ( That is very, VERY frustrating for an emacs/orgmode=20 > newbie. Someone please advise how to turn on a log of keystrokes and=20 > functions being invoked by those keystrokes. ... Consider having this on= =20 > as default for newbies. ) > > =C2=A0It seems to me that to get people started without unnecessary=20 > frustrations, we might want to put into the docs something like: > > To include feature : timestamp-based unique IDs : Configure emacs thusly= =20 > : insertion> and then see how this works ; ...=C2=A0 same for= =20 > features like=C2=A0 HTML export, literal programming, custom timestamp=20 > (perhaps with down-to-seconds resolution) custom, etc > > =C2=A0I believe if I saw in a few screen casts how the orgmode=20 > "professionals" use orgmode, and had access to their sample orgmode=20 > files which I could follow along and literally identically modify during= =20 > the screencast, I would be much father (and perhaps even happier) with=20 > the use of orgmode. I think the most crucial point for newbies is being=20 > able to literally follow the screencast along, perfectly replicating the= =20 > screen cast results in their emacs / evil / spacemacs setup. > > If people would want to send me URLs for their sample .org files for=20 > which they also have a demo screen cast on how to use their features, I=20 > would like to pull these together and create a section for the docs with= =20 > these. > > =C2=A0Guys! You are a wonderful bunch and you are perfecting an amazing= =20 > software! ... Let the world get more of a taste of your amazing work. > > =C2=A0 Thanks so much for orgmode! > > =C2=A0=C2=A0=C2=A0 John