I have been working on Rat and have a set of classes that output markdown.
I think I can make CLI HelpFormtter system take a class to output the data
in any given format.
What rat is doing now is writing help to a file and using APT format to
include that using Velocity.
Gary's point that XML provides broad support, and Eric's point about
markdown and the general case for text seems to indicate that applications
need a way to specify how to format the data, as well as access to the
current tooling that makes generating/aggregating the text easier. I will
work on this and create a pull request where we can discuss how it works.
On Thu, Sep 19, 2024 at 1:00 PM Eric Pugh <ep...@opensourceconnections.com>
wrote:
> I would love to see the ability to output the help docs in a format that
> could be dropped into documentation. In Solr we basically cut and paste
> the -h output into the Reference Guide, it works but it’s ugly and manual.
> I’ve been experimenting with some tools that let you run a tool, capture
> the output, and incorporate that into the help docs.
>
> Imagine if I had a "-h —output markdown" that gave a nice table
> structure? That could then be incorporated directly into the docs and
> generated at build time.
>
> Honestly, if I had to write my own string handling code to actually do the
> output, but the structure was all there, that would be super helpful.
>
> > On Sep 19, 2024, at 7:36 AM, Gary Gregory <garydgreg...@gmail.com>
> wrote:
> >
> > Hi Claude,
> >
> > I think it needs to be flexible/complex just enough to support doing
> what I
> > mentioned. I like XML because once you have that, you can get anywhere
> else
> > with XSL. How do you do transformations in JSON anyway? Has that wheel
> been
> > reinvented? JOLT seems not to have gone anywhere.
> >
> > Maybe we need a PR to get us started to get done what you need to do. WRT
> > formats, at least one can be provided as a test to make sure the code is
> > extensible enough.
> >
> > Gary
> >
> >
> > On Thu, Sep 19, 2024, 6:53 AM Claude Warren <cla...@xenei.com> wrote:
> >
> >> This could get complex fairly quickly. So a couple of questions:
> >>
> >> Q: Do we want to create a new commons project or perhaps expand
> >> commons-text to contain a simple library for formatting output. If we
> do
> >> that we would have to include it in commons-cli which I know is
> >> undesirable, but if text is small enough it should not be a problem.
> >>
> >> Q: Do we want to create/support multiple output formatters (e.g. XML,
> >> XHMTL, Text, markdown)?
> >>
> >>
> >>
> >> On Wed, Sep 18, 2024 at 5:40 PM Gary Gregory <garydgreg...@gmail.com>
> >> wrote:
> >>
> >>> If we create something new, it would be nice to have example in tests
> >> that
> >>> show rendering to XHTML and XML. This means the abstract superclass
> >> should
> >>> not assume console output. A site can use its own CSS for styling. If
> we
> >>> are flexible enough we should not need to create yet another thing in
> >>> the future.
> >>>
> >>> Gary
> >>>
> >>> On Wed, Sep 18, 2024, 11:23 AM Claude Warren <cla...@xenei.com> wrote:
> >>>
> >>>> I think that help formatting really comes down to building a textual
> >>>> matrix from a list of Options. To do this we need to have several
> >> things:
> >>>>
> >>>> 1. A list of headers (text for the columns in the table)
> >>>> 2. The minimum and maximum width for each column. (perhaps as a % of
> >>>> the width)
> >>>> 3. A method that converts the Option into the columns.
> >>>>
> >>>>
> >>>> Interface TableDef {
> >>>> String header();
> >>>> String footer();
> >>>> List<String> columnHeaders();
> >>>> int[] minimumColumnSize();
> >>>> int[] maximumColumnSize();
> >>>> Iterator<List<String>> rows();
> >>>> }
> >>>>
> >>>> abstract class AbstractHelpFormatter {
> >>>> int width;
> >>>> List<TableDef> tables;
> >>>>
> >>>> printUsage(PrintWriter writer, String commandLineSyntax) {
> >>>> // print the command line syntax.
> >>>> for(TableDef table : tables) {
> >>>> writer.println(table.header())
> >>>> for(String line :
> >>>> formatColumns(table.minimumColumnSize(), table.maximumColumnSize(),
> >>>> columnHeaders())) {
> >>>> writer.println(line);
> >>>> }
> >>>> Iterator<List<String>> rows = table.rows();
> >>>> while(rows.hasNext()) {
> >>>> formatColumns(table.minimumColumnSize(),
> >>>> table.maximumColumnSize(), row.next()).forEach(writer::println);
> >>>> }
> >>>> writer.println(table.footer())
> >>>> }
> >>>> }
> >>>> }
> >>>>
> >>>> where formatColumns is a static method in HelpFormatter that will
> >> produce
> >>>> a list of Strings necessary to properly display the wrapped columns.
> >> Any
> >>>> helper functions for formatColumns() would also be public static so
> that
> >>>> they can be reused for other implementations.
> >>>>
> >>>> The concrete implementation would be the implementation we currently
> >> have
> >>>> adapted to fit this pattern.
> >>>>
> >>>> I have code like this in the new RAT code.
> >>>>
> >>>> Does this make sense to you?
> >>>>
> >>>> Claude
> >>>>
> >>>>
> >>>>
> >>>>
> >>>> On Wed, Sep 18, 2024 at 2:57 PM Eric Pugh <
> >>>> ep...@opensourceconnections.com> wrote:
> >>>>
> >>>>> In Solr we added some additional formatting methods to our Tool.java
> >>>>> interface to help with formatting the various tools that use
> >> commons-cli:
> >>>>>
> >>>>> [image: solr.png]
> >>>>>
> >>>>> solr/solr/core/src/java/org/apache/solr/cli/Tool.java at main ·
> >>>>> apache/solr
> >>>>> <
> >>
> https://github.com/apache/solr/blob/main/solr/core/src/java/org/apache/solr/cli/Tool.java#L34
> >>>
> >>>>> github.com
> >>>>> <
> >>
> https://github.com/apache/solr/blob/main/solr/core/src/java/org/apache/solr/cli/Tool.java#L34
> >>>
> >>>>>
> >>>>> <
> >>
> https://github.com/apache/solr/blob/main/solr/core/src/java/org/apache/solr/cli/Tool.java#L34
> >>>
> >>>>>
> >>>>> PackageTool had a very very custom help output that we didn’t want to
> >>>>> lose when we redid things, so it has a custom getHeader:
> >>>>>
> >>>>>
> >>>>>
> >>>>> [image: solr.png]
> >>>>>
> >>>>> solr/solr/core/src/java/org/apache/solr/cli/PackageTool.java at main
> ·
> >>>>> apache/solr
> >>>>> <
> >>
> https://github.com/apache/solr/blob/main/solr/core/src/java/org/apache/solr/cli/PackageTool.java#L251
> >>>
> >>>>> github.com
> >>>>> <
> >>
> https://github.com/apache/solr/blob/main/solr/core/src/java/org/apache/solr/cli/PackageTool.java#L251
> >>>
> >>>>>
> >>>>> <
> >>
> https://github.com/apache/solr/blob/main/solr/core/src/java/org/apache/solr/cli/PackageTool.java#L251
> >>>
> >>>>>
> >>>>> Whereas CreateTool had a short bit of additional text, and then the
> >>>>> options:
> >>>>>
> >>
> https://github.com/apache/solr/blob/main/solr/core/src/java/org/apache/solr/cli/CreateTool.java#L70
> >>>>>
> >>>>> And our PostLogsTool doesn’t use any of those extra formatting
> helpers:
> >>>>>
> >>
> https://github.com/apache/solr/blob/main/solr/core/src/java/org/apache/solr/cli/PostLogsTool.java
> >>>>>
> >>>>>
> >>>>> I do wish this had been part of commons-cli!
> >>>>>
> >>>>> Eric
> >>>>>
> >>>>>
> >>>>>
> >>>>> On Sep 18, 2024, at 9:52 AM, Gary Gregory <garydgreg...@gmail.com>
> >>>>> wrote:
> >>>>>
> >>>>> Or a new better formatting class?
> >>>>>
> >>>>> Gary
> >>>>>
> >>>>> On Wed, Sep 18, 2024, 9:45 AM Claude Warren <cla...@xenei.com>
> wrote:
> >>>>>
> >>>>> After more exploration it seems that HelpFormatter is really not
> >> designed
> >>>>> to be extended. I will have to rethink this. It may make sense to
> >> make
> >>>>> some of the HelpFormatter methods static so that they can be used in
> >>>>> other
> >>>>> implementations.
> >>>>>
> >>>>> On Wed, Sep 18, 2024 at 9:29 AM Claude Warren <cla...@xenei.com>
> >> wrote:
> >>>>>
> >>>>> Greetings,
> >>>>>
> >>>>> I have a case in RAT where we want to append a line to the help text
> >> when
> >>>>> the option has multiple arguments or when we have defined a default
> >>>>>
> >>>>> value.
> >>>>>
> >>>>>
> >>>>> I have implemented this in a renderOptions() implementation in CLI
> >> 1.8.0.
> >>>>> In both cases we use the Option to check for some state and then
> append
> >>>>>
> >>>>> to
> >>>>>
> >>>>> the optBuf.
> >>>>>
> >>>>> I am now migrating to 1.9.0 and have to do the same thing, but 1.9.0
> >> adds
> >>>>> more functionality to the default renderOptions() method so I have to
> >>>>> rework my implementation. However, had I not known this was the
> case,
> >> I
> >>>>> would have missed the changes and we would have had some rather
> >>>>>
> >>>>> interesting
> >>>>>
> >>>>> bugs later.
> >>>>>
> >>>>> What I am proposing is a new parameter to renderOptions(). A
> >>>>> "Optional<String> Function<Option>". If the function returns a
> String
> >>>>>
> >>>>> then
> >>>>>
> >>>>> it is appended to the optBuf.
> >>>>>
> >>>>> This method would be called near the end of renderOptions.
> >>>>>
> >>>>> Thoughts?
> >>>>> Claude
> >>>>>
> >>>>> --
> >>>>> LinkedIn: http://www.linkedin.com/in/claudewarren
> >>>>>
> >>>>>
> >>>>>
> >>>>> --
> >>>>> LinkedIn: http://www.linkedin.com/in/claudewarren
> >>>>>
> >>>>>
> >>>>> _______________________
> >>>>> *Eric Pugh **| *Founder | OpenSource Connections, LLC | 434.466.1467
> |
> >>>>> http://www.opensourceconnections.com | My Free/Busy
> >>>>> <http://tinyurl.com/eric-cal>
> >>>>> Co-Author: Apache Solr Enterprise Search Server, 3rd Ed
> >>>>> <
> >>
> https://www.packtpub.com/big-data-and-business-intelligence/apache-solr-enterprise-search-server-third-edition-raw
> >>>
> >>>>> This e-mail and all contents, including attachments, is considered to
> >> be
> >>>>> Company Confidential unless explicitly stated otherwise, regardless
> >>>>> of whether attachments are marked as such.
> >>>>>
> >>>>>
> >>>>
> >>>> --
> >>>> LinkedIn: http://www.linkedin.com/in/claudewarren
> >>>>
> >>>> ---------------------------------------------------------------------
> >>>> To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
> >>>> For additional commands, e-mail: dev-h...@commons.apache.org
> >>>
> >>>
> >>
> >> --
> >> LinkedIn: http://www.linkedin.com/in/claudewarren
> >>
>
> _______________________
> Eric Pugh | Founder | OpenSource Connections, LLC | 434.466.1467 |
> http://www.opensourceconnections.com <
> http://www.opensourceconnections.com/> | My Free/Busy <
> http://tinyurl.com/eric-cal>
> Co-Author: Apache Solr Enterprise Search Server, 3rd Ed <
> https://www.packtpub.com/big-data-and-business-intelligence/apache-solr-enterprise-search-server-third-edition-raw>
>
> This e-mail and all contents, including attachments, is considered to be
> Company Confidential unless explicitly stated otherwise, regardless of
> whether attachments are marked as such.
>
>
--
LinkedIn: http://www.linkedin.com/in/claudewarren
