discount icon indicating copy to clipboard operation
discount copied to clipboard

GitHub/GitLab -like README generation

Open Kimplul opened this issue 3 years ago • 2 comments

Hi, here's a small list of patches I've added for my use case. Feel free to ignore or cherrypick, I'll just post these here in case anyone else finds them useful.

List of commits:

  1. improve parallel compilation

    GNU Make run in palallel complains about libmarkdown missing, apparently because the tests were trying to build before the library. Fixes that issue.

  2. add hopthelp

    Adds markdown -h as a legitimate option that just dumps the flags and their descriptions before exiting.

  3. add taganchor option

    The -ftaganchor flag outputs anchors with inline NULL <a class="anchor"> tags, similar to the default behaviour, but they're inside the heading and the heading IDs get applied a prefix. This more or less guarantees that there can be no accidental CSS pickups, as long as I make sure to not use that prefix in my CSS.

    Also adds the -a flag, which sets the prefix to be used.

    With these these options, I am able to generate something very close to GitHub/GitLab READMEs, with headings that have a link button that appears when hovering with the following CSS:

    .anchor::before {
     content: "🔗";
     margin-right: 0.5em;
     font-size: 12pt;
    }
    
    .anchor {
     visibility: hidden;
    }
    
    h1:hover .anchor,
    h2:hover .anchor,
    h3:hover .anchor,
    h4:hover .anchor,
    h5:hover .anchor,
    h6:hover .anchor {
     visibility: visible;
    }
    
  4. add fencedinline option

    Currently when using -ffencedcode there's a newline that is added after the <pre><code> combo, which results in a somewhat ugly forehead when combined with a background color, for example. This flag removes that newline, giving me nice and slim fenced code blocks, again very close to what GitHub/GitLab renders.

Kimplul avatar Jul 28 '22 16:07 Kimplul

I'd already been working on the buglets with parallel make when I finally saw this pull request, sorry, so it's already got a collision with the mainline. That said, these are all reasonable feature requests! ) The parallel make bugs are complicated by my wanting discount to work on netbsd & (older) freebsds; you use $< in the .c.o rule for tests/exerciser/flags, but the bsd make on these two machines populates $< with the last dependency, not the first, so that rule fails on my netbsd & freebsd machines (probably also my minix3 build machine, but my continuous testing toolbox has already thrown back an error at me) and I had to implement a slightly different solution.

The leading newline on fenced code blocks is, arguable, a bug; the reference implementation doesn't do fenced code, so the reference for fenced code is whichever markdown derivative first implemented it. Not tossing in an extra leading newline is obviously the correct format, so I've removed it across the board.

I thought I'd already implemented a verbose listing of flags in hoptopt, but it turns out that no, I didn't. I may use a different way to get a verbose listing of the flags; use -? & -?? (like I use -f? to get a list of the usable runtime options.)

The table of contents code is a bit of a dog's breakfast, so I may implement your proposal as the default, and put in a prefix setter interface for it.

(I've already put in the parallel make & fenced code block fixes; I may cherrypick your pull request for the TOC fix, and I'm thinking about an elegant (for orcish values of elegant) solution for the toc anchor behavior you've reported.)

Orc avatar Jul 31 '22 07:07 Orc

Sounds great, thanks for taking a look.

Kimplul avatar Jul 31 '22 08:07 Kimplul

I believe I've already made patches for all of these, so I'm going to close this pull request.

Orc avatar Feb 07 '24 06:02 Orc