simonmichael
Hledger info pages top page looks and acts like a man page
Description
The hledger top page, i.e. the page shown first when viewing the manual looks like a man page.
The top page should use the stylized/capitalized name of the program. I also should only provide a short description to leave the more detailed information such as synopsis to the pages following.
The menu has the same issues with some entries written in caps and no indentation/subpages for each part or chapter. Further it doesn't have an index either.
For reference compare the manual ledger-cli: https://ledger-cli.org/doc/ledger-mode.html
System information
- hledger 1.43.2, linux-x86_64`
- openSUSE Tumbleweed
Thanks for the report. I think you are viewing the manual via the website, eg https://hledger.org/1.43/hledger.html , and you feel that web page has too much man-page-style boilerplate at the top, so you have to scroll to see useful content ? Have I understood ? Please clarify.
Or, is it about the info manual that you see eg when you run hledger --info ? Here's what I get from that:
Next: PART 1 USER INTERFACE, Up: (dir)
hledger(1)
**********
hledger - a robust, friendly plain text accounting app (command line
version).
'hledger'
or
'hledger COMMAND [OPTS] [ARGS]'
or
'hledger ADDONCMD [OPTS] -- [ADDONOPTS] [ADDONARGS]'
hledger is a robust, user-friendly, cross-platform set of programs
for tracking money, time, or any other commodity, using double-entry
accounting and a simple, editable file format. hledger is inspired by
and largely compatible with ledger(1), and largely interconvertible with
beancount(1).
This manual is for hledger's command line interface, version 1.43.
It also describes the common options, file formats and concepts used by
all hledger programs. It might accidentally teach you some
bookkeeping/accounting as well! You don't need to know everything in
here to use hledger productively, but when you have a question about
functionality, this doc should answer it. It is detailed, so do skip
ahead or skim when needed. You can read it on hledger.org, or as an
info manual or man page on your system. You can also open a built-in
copy, at a point of interest, by running
'hledger --man [CMD]', 'hledger --info [CMD]' or 'hledger help [TOPIC]'.
...
Simon Michael @.***> writes:
Or, is it about the info manual that you see eg when you run
hledger --info? Here's what I get from that:
Yes I'm viewing the Info page that way, using calling info hledger.info or opening it inside Emacs's info viewer.
As said compare the layout of hledger's manual to the one of ledger for the layout and chapter/sub-chapter items.
Your report was a bit confusing. Ledger's info manual looks most like a man page:
LEDGER(1) General Commands Manual LEDGER(1)
NAME
ledger - Command-line, double-entry account reporting tool
SYNOPSIS
ledger [options] [command] [arguments]
DESCRIPTION
ledger is a command-line accounting tool based on the power and
completeness of double-entry accounting. It is only a reporting tool,
which means it never modifies your data files, but it does offer a large
selection of reports, and different ways to customize them to your needs.
COMMANDS
ledger accepts several top-level commands, each of which generates a
different kind of basic report. Most of them accept a report-query
argument, in order to determine what should be reported. To understand
the syntax of a report-query, see the section on QUERIES. In its most
basic form, simply specifying one or more strings produces a report for
all accounts containing those strings.
If no command is given, ledger enters a REPL, or command loop, allowing
several commands to be executed on the same dataset without reparsing.
The following is a complete list of accepted reporting commands:
accounts [report-query]
List all accounts for postings that match the report-query.
...
I think you meant ledger-mode's info manual, which has less text on the top page:
Next: Introduction to Ledger-mode, Prev: (dir), Up: (dir)
(ledger-mode)Top
Overview
********
Ledger is a command line accounting tool that provides double-entry
accounting based on a text journal. It provides no bells or whistles,
and returns the user to the days before user interfaces were even a
twinkling in their father’s CRT.
Ledger-mode assists you in maintaining input files for Ledger,
running reports and much more...
* Menu:
* Introduction to Ledger-mode
* The Ledger Buffer
* The Reconcile Buffer
* The Report Buffer
* Scheduling Transactions
* Customizing Ledger-mode
* Generating Ledger Regression Tests
* Embedding Example results in Ledger Documentation
* Hacking Ledger-mode
* Concept Index
* Command & Variable Index
* Keystroke Index
I agree that's probably better. But, changing this requires considering the impact on the other manual formats (txt, man, html), because they are generated from the same source.
PS, for the other issues you mentioned, please give an example of each if they are important, so I'll understand.
Simon Michael @.***> writes:
simonmichael left a comment (simonmichael/hledger#2438)
Your report was a bit confusing. Ledger's info manual looks most like a man page:
Which is the issue I'm reporting.
I think you meant hledger's info manual should be more like ledger-mode's, with more brief text at the top level:
Not directly that it should look like ledger-mode's manual but it's manual was the best reference I could find given the related topics.
I agree that's probably better. But, changing this requires considering the impact on the other manual formats (txt, man, html), because they are generated from the same source.
For text and HTML there should be no issues but for man pages the layout wouldn't match anymore. The issue is that man pages is quite long usually man pages don't get that long and when they are usually split up e.g. in the case of git. A full manual doesn't fit into a man page usually.
Simon Michael @.***> writes:
simonmichael left a comment (simonmichael/hledger#2438)
PS, for the other issues you mentioned, please give an example of each if they are important, so I'll understand.
Do I understand correctly that the pages for each PART <NUMBER> <TOPIC> are subpages of said part? In that case the should be grouped
as such.
For the index try to call info and open any manual press i or I and check it. The index allows to search for keywords in the manual so it's easier to navigate between the pages when trying to find a specific topic related to said keyword.
Hi @Thaodan, sorry for losing track of this. (Issues which don't yet have a BUG or WISH categorisation are less visible, it seems.)
Doc organisation and presention is complex and hard to discuss. If you have time, could we discuss it in chat ? https://hledger.org/support.html