;doc: FILES: redo with gtree, add more

This commit is contained in:
Simon Michael 2022-12-05 09:35:37 -10:00
parent 688e392ce9
commit 6137f7003d

View File

@ -5,147 +5,805 @@
<!-- toc --> <!-- toc -->
</div> </div>
Overviews of files in the hledger project, as of 2022-12. Some views and explanations of files in the hledger project, as of 2022-12.
## hledger repo directories <br clear=all>
## hledger working copy
A full working copy of the official hledger [repos](REPOS.html)
is best laid out like this (manually; we currently don't use git submodules):
<pre> <pre>
$ (cd ~/src/hledger; tre -d) src/hledger/ - git clone https://github.com/simonmichael/hledger; cd hledger
. finance/ - git clone https://github.com/simonmichael/hledger_finance finance
├── .github site/ - git clone https://github.com/simonmichael/hledger_site site
│ ├── ISSUE_TEMPLATE </pre>
│ └── workflows
│ └── old You don't need to clone all of these repos unless you are working in all of those areas.
├── .sandstorm
├── bin The next two listings show the directories in the main and site repos:
├── checks
├── doc ## main repo directories
│ ├── haskellerz
│ ├── hcar The main repo contains
│ ├── mockups the hledger-lib, hledger, hledger-ui, and hledger-web haskell packages,
│ └── profs the hledger-install script,
├── docker-static-arm32v7 a collection of example data,
├── docker some documentation
├── examples and other support files.
│ ├── budgeting
│ ├── csv <!-- commands are starting points, manual fixups applied -->
│ ├── investing <!-- $ (cd ~/src/hledger; tools/gtree -d) -->
│ ├── invoicing <pre>
│ │ ├── invoice-script src/hledger/
│ │ └── makefile .github/
│ ├── reports ISSUE_TEMPLATE/
│ ├── systemd workflows/
│ └── templates old/
│ └── basic .sandstorm/
├── hledger-install bin/
├── hledger-lib checks/
│ ├── Hledger doc/
│ │ ├── Data haskellerz/
│ │ │ └── JournalChecks hcar/
│ │ ├── Read mockups/
│ │ ├── Reports profs/
│ │ └── Utils docker-static-arm32v7/
│ ├── Text docker/
│ │ ├── Megaparsec examples/
│ │ └── Tabular budgeting/
│ ├── other csv/
│ │ └── ledger-parse investing/
│ │ └── Ledger invoicing/
│ │ └── Parser invoice-script/
│ └── test makefile/
├── hledger-ui reports/
│ ├── Hledger systemd/
│ │ └── UI templates/
│ └── test basic/
├── hledger-web hledger-install/
│ ├── Hledger hledger-lib/
│ │ └── Web Hledger/
│ │ ├── Handler Data/
│ │ ├── Settings JournalChecks/
│ │ └── Widget Read/
│ ├── app Reports/
│ ├── config Utils/
│ ├── deploy Text/
│ ├── static Megaparsec/
│ │ ├── css Tabular/
│ │ ├── fonts other/
│ │ └── js ledger-parse/
│ ├── templates Ledger/
│ └── test Parser/
├── hledger test/
│ ├── Hledger hledger-ui/
│ │ └── Cli Hledger/
│ │ └── Commands UI/
│ ├── app test/
│ ├── bench hledger-web/
│ ├── embeddedfiles Hledger/
│ ├── shell-completion Web/
│ └── test Handler/
│ ├── addons Settings/
│ ├── balance Widget/
│ ├── cli app/
│ ├── errors config/
│ ├── i18n deploy/
│ ├── import static/
│ ├── journal css/
│ │ └── account-display-order fonts/
│ │ └── 1 js/
│ ├── print templates/
│ └── register test/
└── tools hledger/
Hledger/
Cli/
Commands/
app/
bench/
embeddedfiles/
shell-completion/
test/
addons/
balance/
cli/
errors/
i18n/
import/
journal/
account-display-order/
1/
print/
register/
tools/
</pre> </pre>
## site repo directories ## site repo directories
The site repo contains the website infrastructure,
versioned snapshots of the user manuals,
home page, cookbook and other docs.
<!-- $ (cd ~/src/hledger/site; ../tools/gtree -d) -->
<pre> <pre>
$ (cd ~/src/hledger/site; tre -d) src/hledger/site/
. css/
├── css js/
├── js src/
├── src 1.0/
│ ├── 1.0 1.1/
│ ├── 1.1 1.10/
│ ├── 1.10 1.11/
│ ├── 1.11 1.12/
│ ├── 1.12 1.13/
│ ├── 1.13 1.14/
│ ├── 1.14 1.15/
│ ├── 1.15 1.16/
│ ├── 1.16 1.17/
│ ├── 1.17 1.18/
│ ├── 1.18 1.19/
│ ├── 1.19 1.2/
│ ├── 1.2 1.20/
│ ├── 1.20 1.21/
│ ├── 1.21 1.22/
│ ├── 1.22 1.23/
│ ├── 1.23 1.24/
│ ├── 1.24 1.25/
│ ├── 1.25 1.26/
│ ├── 1.26 1.27/
│ ├── 1.27 1.28/
│ ├── 1.28 1.3/
│ ├── 1.3 1.4/
│ ├── 1.4 1.5/
│ ├── 1.5 1.9/
│ ├── 1.9 dev/
│ ├── dev fonts/
│ ├── fonts highslide/
│ ├── highslide graphics/
│ │ └── graphics outlines/
│ │ └── outlines images/
│ └── images hledger-ui/
│ ├── hledger-ui hledger-web/
│ └── hledger-web normal/
│ ├── normal small/
│ └── small theme/
└── theme css/
└── css
</pre> </pre>
## finance repo directories ## finance repo
The finance repo contains transaction journals and financial reports.
<!-- $ (cd ~/src/hledger/finance; ../tools/gtree) -->
<pre> <pre>
$ (cd ~/src/hledger/finance; tre -d) src/hledger/finance/
. Makefile
README.md
oc.accounts
oc.csv
oc.csv.rules
oc.journal
</pre> </pre>
## hledger user scripts
[Scripts](scripts.html) for users are in bin/:
<!-- $ gtree ^bin -->
<pre>
src/hledger/bin/
README.md
_hledger-chart.hs
bashrc
compile.sh
csv.mk
hledger-addon-example.hs
hledger-balance-as-budget.hs
hledger-check-fancyassertions.hs
hledger-check-postable.hs
hledger-check-tagfiles.cabal.hs
hledger-check-tagfiles.hs
hledger-combine-balances.hs
hledger-git
hledger-move.hs
hledger-pijul
hledger-print-location.hs
hledger-simplebal
hledger-smooth.hs
hledger-swap-dates.hs
paypaljson
paypaljson2csv
scripts.test
watchaccounts
</pre>
## hledger developer tools
Scripts used by developers and maintainers tend to be in tools/:
<!-- $ gtree ^tools -->
<pre>
src/hledger/tools/
README
changelog.hs
commitlint
criterionbench.hs
dayssincetag.hs
docshelltest.hs
generatejournal.hs
generatetimeclock.hs
gtree
hackageupload
listbydeps.hs
pandoc-dedent-code-blocks.lua
pandoc-demote-headers.lua
pandoc-drop-html-blocks.lua
pandoc-drop-html-inlines.lua
pandoc-drop-links.lua
pandoc-drop-toc.lua
pandoc-toc.lua
pandoc-wiki-links.lua
progressionbench.hs
regressiontest.py
release
runhledgercov
simplifyprof.hs
trhsx
</pre>
## Sh/makefiles
Many developer tasks are automated with make and/or shake, also.
<!-- $ gtree '(^|/)((bsd)?m|sh)ake' -->
<pre>
src/hledger/
Makefile
Makefile.helpsys
Shake.hs
doc/
MAKE.md
SHAKE.md
haskellerz/
Makefile
examples/
invoicing/
makefile/
Makefile
reports/
Makefile
hledger/
shell-completion/
BSDmakefile
Makefile
test/
errors/
Makefile
</pre>
## YAML files
Developer configuration often happens in .yaml or .yml files.
<!-- $ gtree ya?ml -->
<pre>
src/hledger/
.hlint.yaml
azure-pipelines.yml
hie-other.yaml
stack.yaml
stack8.10.yaml
stack9.0.yaml
stack9.4.yaml
.github/
FUNDING.yml
ISSUE_TEMPLATE/
config.yml
workflows/
binaries-linux-arm32v7-static.yml
binaries-linux-x64-static.yml
binaries-mac-x64.yml
binaries-windows-x64.yml
test-linux-x64.yml
old/
release.yml
hledger-lib/
package.yaml
hledger-ui/
package.yaml
hledger-web/
package.yaml
config/
keter.yaml
settings.yml
hledger/
package.yaml
</pre>
## Core docs
Core documentation which should stay closely synced with hledger's implementation
(changelogs, user manuals, developer docs) is kept in the main repo.
- Many directories have a README.md explaining their purpose and content.
- Each hledger package, and the project itself, has a CHANGES.md changelog file.
- hledger/hledger.m4.md, hledger-ui/hledger-ui.m4.md, hledger-web/hledger-web.m4.md
are the user manuals, which get rendered as html, info, man and plain text.
They are processed first with m4 for extra flexibility.
- The hledger manual imports subcommand docs from hledger/Hledger/Cli/Commands/*.md.
- doc/ contains other developer docs.
<!-- $ gtree md -->
<pre>
src/hledger/
CHANGES.md
README.md
.github/
pull_request_template.md
ISSUE_TEMPLATE/
a-bug.md
a-wish.md
.sandstorm/
README.md
changelog.md
description.md
bin/
README.md
doc/
ACHIEVEMENTS.md
BENCHMARKS.md
CHANGELOGS.md
CODE.md
COMMITS.md
CONTRIBUTING.md
CREDITS.md
DOCS.md
EXAMPLES.md
FILES.md
FINANCE.md
ISSUES.md
LINKS.md
MAKE.md
PULLREQUESTS.md
RELEASING.md
REPOS.md
SHAKE.md
TESTS.md
VERSIONNUMBERS.md
WORKFLOWS.md
github-release-doc.tmpl.md
haskellerz/
haskellerz.md
hcar/
HCAR-hledger-201611.md
docker/
README.md
examples/
invoicing/
README.md
invoice-script/
README.md
abinvoice.tmpl.md
makefile/
202001ab.md
README.md
systemd/
hledger-web.service
hledger.nginx
readme.md
templates/
README.md
hledger-install/
README.md
hledger-lib/
CHANGES.md
README.md
hledger-ui/
CHANGES.md
README.md
hledger-ui.m4.md
test/
uitest.md
hledger-web/
CHANGES.md
README.md
hledger-web.m4.md
hledger/
CHANGES.md
README.md
hledger.m4.md
Hledger/
Cli/
Commands/
Accounts.md
Activity.md
Add.md
Aregister.md
Balance.md
Balancesheet.md
Balancesheetequity.md
Cashflow.md
Check.md
Close.md
Codes.md
Commodities.md
Descriptions.md
Diff.md
Files.md
Help.md
Import.md
Incomestatement.md
Notes.md
Payees.md
Prices.md
Print.md
Printunique.md
README.md
Register.md
Registermatch.md
Rewrite.md
Roi.md
Stats.md
Tags.md
Test.md
shell-completion/
README.md
test/
README.md
errors/
README.md
</pre>
## Additional docs
Additional docs (intro pages, faqs, tutorials, cookbook..)
are kept in the site repo's src/ directory.
Developer docs (UPPERCASE) and the latest dev manuals (dev/*.md) from
the main repo are also symbolically linked there, so that they too
appear on the website.
<!-- $ cd site; gtree md -->
<pre>
src/hledger/site/src/
ACHIEVEMENTS.md
BACKLOG.md
BENCHMARKS.md
CHANGELOGS.md
CODE.md
COMMITS.md
CONTRIBUTING.md
CREDITS.md
DOCS.md
ERRORS.md
EXAMPLES.md
FILES.md
FINANCE.md
ISSUES.md
LINKS.md
MAKE.md
PULLREQUESTS.md
RELEASING.md
REPOS.md
ROADMAP.md
SHAKE.md
SUMMARY.md
TESTS.md
VERSIONNUMBERS.md
WORKFLOWS.md
accounting.md
add.md
balancing-the-accounting-equation.md
beancount.md
budgeting-and-forecasting.md
budgeting.md
change-account-name-separator.md
charts.md
checking-for-errors.md
command-line-completion.md
common-journal-entries.md
common-workflows.md
conversion2.md
cookbook.md
create-a-journal.md
currency-conversion.md
dev-README.md
dev.md
devfaq.md
dsq.md
editors.md
export.md
faq.md
features.md
financerepo.md
finfaq.md
forecasting.md
foreign-trip-expenses.md
gain.md
gnucash.md
hledger-web-tips.md
import-csv.md
index.md
install.md
inventory.md
investments.md
invoicing.md
ledger.md
loans.md
manuals.md
mobile-apps.md
mockups.md
multicurrency-tutorial.md
project-accounting.md
quicken.md
quickintro.md
quickstart.md
release-notes.md
report-examples.md
rewrite-account-names.md
rewrite-commodity-symbols.md
roi.md
save-frequently-used-options.md
scripting.md
scripts.md
simons-setup.md
snippets.md
sponsor.md
sqlite.md
start.md
support.md
tags-tutorial.md
time-planning.md
time-to-money.md
track-changes-with-version-control.md
track-investments.md
ui.md
userfaq.md
videos.md
web.md
1.0/
csv.md
hledger-api.md
hledger-ui.md
hledger-web.md
hledger.md
journal.md
timeclock.md
timedot.md
1.1/
csv.md
hledger-api.md
hledger-ui.md
hledger-web.md
hledger.md
journal.md
timeclock.md
timedot.md
1.10/
csv.md
hledger-api.md
hledger-ui.md
hledger-web.md
hledger.md
journal.md
timeclock.md
timedot.md
1.11/
csv.md
hledger-api.md
hledger-ui.md
hledger-web.md
hledger.md
journal.md
timeclock.md
timedot.md
1.12/
csv.md
hledger-api.md
hledger-ui.md
hledger-web.md
hledger.md
journal.md
timeclock.md
timedot.md
1.13/
csv.md
hledger-api.md
hledger-ui.md
hledger-web.md
hledger.md
journal.md
timeclock.md
timedot.md
1.14/
csv.md
hledger-api.md
hledger-ui.md
hledger-web.md
hledger.md
journal.md
timeclock.md
timedot.md
1.15/
csv.md
hledger-ui.md
hledger-web.md
hledger.md
journal.md
timeclock.md
timedot.md
1.16/
csv.md
hledger-ui.md
hledger-web.md
hledger.md
journal.md
timeclock.md
timedot.md
1.17/
csv.md
hledger-ui.md
hledger-web.md
hledger.md
journal.md
timeclock.md
timedot.md
1.18/
csv.md
hledger-ui.md
hledger-web.md
hledger.md
journal.md
timeclock.md
timedot.md
1.19/
csv.md
hledger-ui.md
hledger-web.md
hledger.md
journal.md
timeclock.md
timedot.md
1.2/
csv.md
hledger-api.md
hledger-ui.md
hledger-web.md
hledger.md
journal.md
timeclock.md
timedot.md
1.20/
csv.md
hledger-ui.md
hledger-web.md
hledger.md
journal.md
timeclock.md
timedot.md
1.21/
hledger-ui.md
hledger-web.md
hledger.md
1.22/
hledger-ui.md
hledger-web.md
hledger.md
1.23/
hledger-ui.md
hledger-web.md
hledger.md
1.24/
hledger-ui.md
hledger-web.md
hledger.md
1.25/
hledger-ui.md
hledger-web.md
hledger.md
1.26/
hledger-ui.md
hledger-web.md
hledger.md
1.27/
hledger-ui.md
hledger-web.md
hledger.md
1.28/
hledger-ui.md
hledger-web.md
hledger.md
1.3/
csv.md
hledger-api.md
hledger-ui.md
hledger-web.md
hledger.md
journal.md
timeclock.md
timedot.md
1.4/
csv.md
hledger-api.md
hledger-ui.md
hledger-web.md
hledger.md
journal.md
timeclock.md
timedot.md
1.5/
csv.md
hledger-api.md
hledger-ui.md
hledger-web.md
hledger.md
journal.md
timeclock.md
timedot.md
1.9/
csv.md
hledger-api.md
hledger-ui.md
hledger-web.md
hledger.md
journal.md
timeclock.md
timedot.md
dev/
hledger-ui.md
hledger-web.md
hledger.md
</pre>
## Site config files
These help configure the website.
- [book.toml](https://github.com/simonmichael/hledger_site/blob/master/book.toml) is the main config file for mdbook.
- [src/SUMMARY.md](https://github.com/simonmichael/hledger_site/blob/master/src/SUMMARY.md)
defines the site's pages and which ones appear in the sidebar
(except for old manual versions which are rendered separately).
<!-- $ gtree 'Makefile|toml|css|js|theme|SUMMARY' -->
<pre>
src/hledger/site/
Makefile
book.toml
css/
site.css
js/
bootstrap.min.js
jquery-1.11.0.min.js
site.js
src/
SUMMARY.md
highslide/
highslide-ie6.css
highslide.css
highslide.js
theme/
book.js
favicon.png
favicon.svg
highlight.css
highlight.js
index.hbs
css/
chrome.css
general.css
print.css
variables.css
</pre>
<!-- template: -->
<!-- ## title -->
<!-- <\!-- $ gtree ... -\-> -->
<!-- <pre> -->
<!-- </pre> -->
<!-- -->