GNU-style manual for org-trello #394

daniel-birket · 2019-01-28T04:27:51Z

Mr. Dumont,

Please see this barely-begun template of a GNU-style manual for your org-trello package. Assuming that you approve of me investing the time to complete it, it will eventually produce an info-format manual for use within Emacs (like Emacs' own manual), plus HTML, PDF and other format manuals, all from the same org-mode source. I'll pull the content from your source and doc-strings. See graphviz-dot-mode for a finished example (from .texi source).

If you're interested, I'll work on it, time permitting, for your eventual review.

coveralls · 2019-01-28T04:30:32Z

Coverage remained the same at 98.308% when pulling a32371b on daniel-birket:texinfo into 75e9f99 on org-trello:master.

ardumont · 2019-01-28T09:04:48Z

That sounds great.
Many thanks in advance for your time on this.

I don't know if you are aware of the online "manual" [1]
It sure is not perfect but that could be a start (the videos are a bit old but the idea is there ;)

That reminds me of some years back when i tried to do some literate programming (prior to 0.2.6 according to git log).

[1] http://org-trello.github.io/

Cheers,

daniel-birket · 2019-01-30T03:30:27Z

Mr. Dumont,
The structure of the document and branch folder should be clear now. Please review and critique.
All three useful output file-formats are present in sample form: info, html and pdf. The Makefile works if TexInfo is installed. Note the presence of indices at the end. (The key-index failed to merge into the concept index or you would see "C-c o s" there.) View the info file without installing it with "info ./org-trello.info" or open in Emacs in "Info" mode. This html file is single-file format as that works well for small manuals, but a multi-file format like your manual web-site is available.

…ry in table.

…. Convert release-notes to a list to shorten TOC.

ardumont · 2019-01-31T07:42:55Z

texinfo/Makefile

+BaseName	:= org-trello
+OrgSrc		:= $(BaseName).org
+TexiSrc		:= $(BaseName).texi
+TexiInc		:= gpl.texi fdl.texi


Looks like indendation is off?

ardumont · 2019-01-31T07:52:53Z

Thanks, looks like it's going the right way ;)
I have only a small remark about the indentation in the makefile but that's about it so far.

I have non-blocking questions about:

how to compile this? That could be added in a README-doc.org (or something) to explain how it's done. That sure would be great ;)
how to package this? The current packaging is done for el-get (~ recipe), melpa (~ recipe), marmalade (~ tarball created through makefile and push).

Cheers,

…es. Added more Using section headers. Added few more summary key-bindings. Keybinding hook function uses defun for clarity instead of 'mysterious' lamda.

…gacy documents in TODO.org. Added a few more sections: About, Quick-Start, How-to. Detached Release-Notes.org

… notes verbatim (with light cleanup). Graphviz diagram of building manual with Texinfo. (Building with Emacs is another graph.)

ardumont · 2019-02-04T10:01:36Z

Thanks for your work on this, and many thanks for clarifying the manual build instructions ;)

…ADME.

… build/install graphic.

ardumont · 2019-02-17T18:33:50Z

texinfo/org-trello.org

@@ -498,21 +503,29 @@ list items.
 :END:
 This section describes other functions not listed above.

-** TODO How to Perform Tasks
+** TODO How to…
 :PROPERTIES:
 :ALT_TITLE: How to…
 :DESCRIPTION: How to Perform Tasks
 :END:
 This section is describes how to use commands to perform tasks with org-trello.


is describing

or describes as the section below does ;)

daniel-birket · 2019-02-17T18:37:24Z

Ack. I will review aloud eventually when more draft done. Thank you.

________________________________ From: Antoine R. Dumont <notifications@github.com> Sent: Sunday, February 17, 2019 13:34 To: org-trello/org-trello Cc: Daniel Birket; Author Subject: Re: [org-trello/org-trello] GNU-style manual for org-trello (#394) @ardumont commented on this pull request.

________________________________ In texinfo/org-trello.org<#394 (comment)>:

@@ -498,21 +503,29 @@ list items.

:END: This section describes other functions not listed above. -** TODO How to Perform Tasks +** TODO How to… :PROPERTIES: :ALT_TITLE: How to… :DESCRIPTION: How to Perform Tasks :END: This section is describes how to use commands to perform tasks with org-trello. or describes as the section below does ;) — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub<#394 (comment)>, or mute the thread<https://github.com/notifications/unsubscribe-auth/ABdx5N9FU0Nup60V_scUWSEer2q62G2rks5vOaCngaJpZM4aVLfN>.

ardumont

Draft of Developer section ready for review. #+INCLUDEs README-dev.org.
This reviewed commit sounds good.
Couple of typos and some question regarding the CHEK meaning.

ardumont · 2019-02-17T18:34:37Z

texinfo/org-trello.org


-* Contributing to org-trello
+* CHEK Development of org-trello


CHECK?

I see that you use CHEK consistently everywhere (at least in this commit).
What does that convey?

ardumont · 2019-02-17T18:39:35Z

texinfo/org-trello.org

+list by sending an email to:
+
+- subscribe: emacs.org.trello [AT] librelist.com
+- unsubscribe: emacs.org.trello-unsubscribe [AT] librelist.com


wow, i completely forgot about this.
it's there indeed, http://librelist.com/browser/emacs.org.trello/

daniel-birket · 2019-02-17T18:45:18Z

My workflow in .org is todo next work chek (review or test) and done. In this case chek items are ready for your review, although I must admit that I have not self-reviewed them as closely as usual. I was in a hurry that day.

________________________________ From: Antoine R. Dumont <notifications@github.com> Sent: Sunday, February 17, 2019 13:41 To: org-trello/org-trello Cc: Daniel Birket; Author Subject: Re: [org-trello/org-trello] GNU-style manual for org-trello (#394) @ardumont commented on this pull request. Draft of Developer section ready for review. #+INCLUDEs README-dev.org. This reviewed commit sounds good. Couple of typos and some question regarding the CHEK meaning.

________________________________ In texinfo/org-trello.org<#394 (comment)>:

-* Contributing to org-trello +* CHEK Development of org-trello CHECK? I see that you use CHEK consistently everywhere (at least in this commit). What does that convey?

________________________________ In texinfo/org-trello.org<#394 (comment)>:

+and evaluate it with M-x eval-buffer. Then, return to your org-trello

+buffer and repeat the conditions that cause the issue. Copy the +resulting detailed log messages into your bug-report. + +** CHEK Mailing List +:PROPERTIES: +:ALT_TITLE: Mailing List +:DESCRIPTION: Mailing List +:END: + +This project has a mailing list at librelist.com for communication +and community among its users and contributors. You may join the +list by sending an email to: + +- subscribe: emacs.org.trello [AT] librelist.com +- unsubscribe: emacs.org.trello-unsubscribe [AT] librelist.com wow, i completely forgot about this. it's there indeed, http://librelist.com/browser/emacs.org.trello/ — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub<#394 (review)>, or mute the thread<https://github.com/notifications/unsubscribe-auth/ABdx5JTqnhpX1-UIfY3DeTcQTMAS7yDMks5vOaJIgaJpZM4aVLfN>.

ardumont · 2019-02-17T18:46:18Z

texinfo/org-trello.org

+   (except for the position).  So the entity’s position in trello’s board can be
+   slightly different than the one from the buffer.
+
+Orgtrello With Check On Sensible Actions 


I forgot this as well.
That might answer a recent question...
#391

ardumont · 2019-02-17T18:52:22Z

Configuration section ready for review

Sounds good!

Thanks to you, i remember stuff i forgot ;) so thanks again.

…. Please check install section.

…e-reading it. (Did not build html or pdf.)

… complete. Moved images to sub-folder.

… in HTML, once in PDF.

… to "note".

ardumont · 2019-03-02T19:44:07Z

Sounds fine so far (i'm concentrating on the org buffer within commit).

…or accuracy, grammar, style. How-to section and Index work remains.

… Trello. Repair indenting. Command edits. The web-site "Usage" page How-To section material conflicted with the source-code command definitions - probably outdated. As it duplicated material in the new Commands section (organized by command and grouped by subject), I removed it. Capitalized Trello. Edited some commands. Executed org-trello to check some bindings and it reindented everything, which I repaired. (All :PROPERTIES: blocks now have standard org-mode indent matching heading.) Some emacs-lisp blocks acquired tab characters. Adding more indices remains TODO.

…headings with indices. Added many concept indices. This draft covers all sections of the web site, EXCEPT "How-To" and "Videos". I moved the videos to a link under "About" because the videos will never work in the PDF and INFO formats and would suffer in the HTML format, as it is constrained by the Texinfo filter. Suggest that the web site have two branches: videos and manual. I have tenatively left out the "How To" section as the "Commands" format covers much of the same ground AND the material appears to be outdated. I think there is a place for a "How To" ... "Work with Cards", "Work with CheckLists", etc. but it will take more work to recreate those sections accurate to the current version. You may review content (words) in either org, info, html (prettiest) or pdf. PDF may have the best comment tools for detailed review. There are also format issues, but those are after the content. I will also review later. Too soon now. -- Daniel Birket

ardumont · 2019-07-10T12:46:37Z

Any no go prior to merging this?

daniel-birket · 2019-07-10T12:51:38Z

I've not looked at it in a long while (other work priority) and don't recall now but I see "draft complete without How-to section" so its ok by me if you're happy with its state. Can always be fixed or improved later. Go ahead. Thank you for asking.

ardumont · 2019-07-10T12:53:35Z

I've not looked at it in a long while (other work priority) and don't recall now but I see "draft complete without How-to section" so its ok by me if you're happy with its state.

yes, i recall being fine the last time i looked ;)

Can always be fixed or improved later.

Indeed.

Go ahead. Thank you for asking.

Well, thanks for your work on this ;)

Bare Template of Manual. No content.

c799ee8

daniel-birket added 4 commits January 28, 2019 23:30

Add GNU license files

acaef93

Top-Level structure, including indexes.

26213fb

Add initial Makefile and .gitignore

46070fa

Add initial sample texi, info, html and pdf format files

fc24b0b

daniel-birket added 7 commits January 30, 2019 10:35

Included Release Notes.

25c44b5

Add make cleanall to Makefile.

b8ad07c

Fix and separate Indices. Move Release Notes to End. Keybinding summa…

f64b828

…ry in table.

Add TODO list

549796c

Fetch legacy documentation.

609fcfa

Use standard TexInfo location of identification & copying information…

788a215

…. Convert release-notes to a list to shorten TOC.

Added Credits list.

ba2b0c4

ardumont reviewed Jan 31, 2019

View reviewed changes

daniel-birket added 4 commits January 31, 2019 12:15

Remove unnecesary tab characters from Makefile (cosmetic).

e311bc5

Add initial incomplete README.org

84f7ccc

Added Customize key-bindings section, including sample variable indic…

cdf99e2

…es. Added more Using section headers. Added few more summary key-bindings. Keybinding hook function uses defun for clarity instead of 'mysterious' lamda.

Add TODO flags directly to org-trello.org. Create coverage map for le…

731dec8

…gacy documents in TODO.org. Added a few more sections: About, Quick-Start, How-to. Detached Release-Notes.org

ardumont changed the title ~~Can I interest you in a Manual?~~ GNU-style manual for org-trello Feb 2, 2019

ardumont added the doc-improvment Documentation is lacking on a subject. Needs update. label Feb 2, 2019

Expanded README.org, which now INCLUDES into manual. Copied migration…

f951971

… notes verbatim (with light cleanup). Graphviz diagram of building manual with Texinfo. (Building with Emacs is another graph.)

daniel-birket added 4 commits February 4, 2019 11:02

Debug .info install in Makefile. Improve description of install in RE…

77dd857

…ADME.

Adding more section headers. Add legacy -> new mapping to TODO. Fixed…

085f027

… build/install graphic.

Draft of Developer section ready for review. #+INCLUDEs README-dev.org.

d792fa6

Configuration section ready for review.

7fc136a

ardumont reviewed Feb 17, 2019

View reviewed changes

daniel-birket added 5 commits February 23, 2019 22:12

Completed Installation section. Removed previously reviewed CHEK tags…

18f3b36

…. Please check install section.

Quote org-trello consistently. Minor fixes to install section after r…

e17ba60

…e-reading it. (Did not build html or pdf.)

Setup and troubleshooting sections draft complete. Format sub-section…

7dec3f4

… complete. Moved images to sub-folder.

Add logo to top of file above TOC and in About section. Appears twice…

82d897a

… in HTML, once in PDF.

Completed summary of commands table and quick start. Changed "remark"…

dd2c140

… to "note".

daniel-birket added 3 commits March 2, 2019 16:52

Added command descriptions verbatim, including indices. Must review f…

17593bb

…or accuracy, grammar, style. How-to section and Index work remains.

ardumont merged commit 9453955 into org-trello:master Jul 10, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

GNU-style manual for org-trello #394

GNU-style manual for org-trello #394

daniel-birket commented Jan 28, 2019

coveralls commented Jan 28, 2019 •

edited

ardumont commented Jan 28, 2019

daniel-birket commented Jan 30, 2019

ardumont Jan 31, 2019

ardumont commented Jan 31, 2019

ardumont commented Feb 4, 2019

ardumont Feb 17, 2019

ardumont Feb 17, 2019

daniel-birket commented Feb 17, 2019 via email

ardumont left a comment

ardumont Feb 17, 2019

ardumont Feb 17, 2019

daniel-birket commented Feb 17, 2019 via email

ardumont Feb 17, 2019

ardumont commented Feb 17, 2019

ardumont commented Mar 2, 2019

ardumont commented Jul 10, 2019

daniel-birket commented Jul 10, 2019

ardumont commented Jul 10, 2019


		* Contributing to org-trello
		* CHEK Development of org-trello

GNU-style manual for org-trello #394

GNU-style manual for org-trello #394

Conversation

daniel-birket commented Jan 28, 2019

coveralls commented Jan 28, 2019 • edited

ardumont commented Jan 28, 2019

daniel-birket commented Jan 30, 2019

ardumont Jan 31, 2019

Choose a reason for hiding this comment

ardumont commented Jan 31, 2019

ardumont commented Feb 4, 2019

ardumont Feb 17, 2019

Choose a reason for hiding this comment

ardumont Feb 17, 2019

Choose a reason for hiding this comment

daniel-birket commented Feb 17, 2019 via email

ardumont left a comment

Choose a reason for hiding this comment

ardumont Feb 17, 2019

Choose a reason for hiding this comment

ardumont Feb 17, 2019

Choose a reason for hiding this comment

daniel-birket commented Feb 17, 2019 via email

ardumont Feb 17, 2019

Choose a reason for hiding this comment

ardumont commented Feb 17, 2019

ardumont commented Mar 2, 2019

ardumont commented Jul 10, 2019

daniel-birket commented Jul 10, 2019

ardumont commented Jul 10, 2019

coveralls commented Jan 28, 2019 •

edited