hledger icon indicating copy to clipboard operation
hledger copied to clipboard

docs update, including ISO date formatting for doc/mockups

Open bwignall opened this issue 5 years ago • 2 comments

Two small pieces in this PR:

  1. Update to latest output of 'Shake manuals ; stack build', starting from a clean checkout. This was run to ensure environment was working, and was thought to be a prerequisite for any docs work.
  2. Update the two files in doc/mockups that had yyyy/mm/dd formatting to use ISO yyyy-mm-dd formatting.

bwignall avatar Jan 11 '20 17:01 bwignall

Hi @bwignall, thanks for working on doc updates.

mockups/* are throwaway and very low priority - you probably started here for this reason.

I see that your rebuild of the txt manuals has produced some changes in word wrapping - yours seem to be wrapped with less hyphenation. Maybe that's better.

I find it quite hard to get identical results from the doc rendering toolchain on two machines (eg my mac laptop and gnu/linux website server). To avoid continual diffs between us all, we have some options:

  • advise contributors to change master source files (like *.m4.md) only, and have me update the generated files (before release, and as needed/periodically/in some automated fashion). This is kind of the status quo.

  • try to achieve identical results on our machines by installing the same versions of all doc tools. If you want to try this, here's what I currently use. Are yours newer ? Or older ?

~/src/hledger$ ./Shake -B -VV hledger/hledger.txt
sed -E -i -e ''\''s/(_version_}},' '*)\{\{[^}]+/\1{{1.16.99/;' s/(_monthyear_}}, '*)\{\{[^}]+/\1{{January' '2020/;'\''' hledger/defs.m4
m4 -P -DMAN -I hledger doc/common.m4 hledger/defs.m4 hledger/hledger.m4.md | pandoc --strip-comments -f markdown-smart-tex_math_dollars -s --template doc/manpage.nroff --lua-filter$
tbl hledger/hledger.1 | eqn -Tascii | troff -Wall -mandoc -Tascii | grotty -cbuo > hledger/hledger.txt
warning: file 'hledger/hledger.1', around line 515:
  table wider than line width
warning: file 'hledger/hledger.1', around line 1359:
  table wider than line width
Build completed in 0.99s

~/src/hledger$ m4 --version
m4 (GNU M4) 1.4.18
Copyright (C) 2016 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Written by Rene' Seindal.
~/src/hledger$ pandoc --version
pandoc 2.9.1
Compiled with pandoc-types 1.20, texmath 0.12, skylighting 0.8.3
Default user data directory: /Users/simon/.local/share/pandoc or /Users/simon/.pandoc
Copyright (C) 2006-2019 John MacFarlane
Web:  http://pandoc.org
This is free software; see the source for copying conditions.
There is no warranty, not even for merchantability or fitness
for a particular purpose.
~/src/hledger$ tbl --version
GNU tbl (groff) version 1.22.4
~/src/hledger$ eqn --version
GNU eqn (groff) version 1.22.4
~/src/hledger$ troff --version
GNU troff (groff) version 1.22.4
~/src/hledger$ grotty --version
GNU grotty (groff) version 1.22.4

simonmichael avatar Jan 12 '20 21:01 simonmichael

My "reasoning" was even simpler: I was starting at the top of the output of git grep '[0-9][0-9][0-9][0-9]/[0-9][0-9]/[0-9][0-9]' | grep -v 'journal' | grep -v CHANGES | head -30 and working my way down (after checking that the files would not be clobbered by ./Shake manuals ; stack build). I submitted early on, to get feedback before spending too much time working through the list.

Below are my versions for the same.

SEP='<<<--->>>' ; m4 --version ; echo $SEP ; pandoc --version ; echo $SEP ; tbl --version ; echo $SEP ; eqn --version ; echo $SEP ; troff --version ; echo $SEP ; grotty --version
m4 (GNU M4) 1.4.18
Copyright (C) 2016 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Written by Rene' Seindal.
<<<--->>>
pandoc 2.9.1.1
Compiled with pandoc-types 1.20, texmath 0.12, skylighting 0.8.3
Default user data directory: /home/brian/.local/share/pandoc or /home/brian/.pandoc
Copyright (C) 2006-2019 John MacFarlane
Web:  https://pandoc.org
This is free software; see the source for copying conditions.
There is no warranty, not even for merchantability or fitness
for a particular purpose.
<<<--->>>
GNU tbl (groff) version 1.22.3
<<<--->>>
GNU eqn (groff) version 1.22.3
<<<--->>>
GNU troff (groff) version 1.22.3
<<<--->>>
GNU grotty (groff) version 1.22.3

A quick update of my groff (to match your versions), followed by `./Shake clean ; ./Shake manuals ; stack build' in my branch does not show modifications to any files (that is, it keeps the files as in this PR). This has me inclined toward the current status quo.

Please feel free to close or cherry-pick this PR, as you see fit. If it's best to start with *.m4.md, happy to focus early efforts there.

bwignall avatar Jan 13 '20 02:01 bwignall