I ran into this problem previously as well; it's also interesting that the
build will break if the length of the heading is much longer/shorter than
the length of the underline (I think a difference of more than 2 characters
causes a build error).
Here is a Python and shell script I wrote to do the fix for an entire repo:
#!/usr/bin/python
import re
import sys
def main(argv):
# http://asciidoctor.org/docs/asciidoc-recommended-practices/#section-titles
patterns = [
(re.compile('^=+$'), '='),
(re.compile('^-+$'), '=='),
(re.compile('^~+$'), '==='),
(re.compile('^\^+$'), '===='),
(re.compile('^\++$'), '====='),
]
with open(argv[1], 'r') as input_file:
prev_line = None
curr_line = None
for line in input_file.readlines():
prev_line = curr_line
curr_line = line
if prev_line is None:
continue
for pattern, heading in patterns:
if pattern.match(curr_line) and len(prev_line) ==
len(curr_line):
sys.stdout.write('%s %s' % (heading, prev_line))
prev_line = None
curr_line = None
break
if prev_line is not None:
sys.stdout.write(prev_line)
# end for
if curr_line is not None:
sys.stdout.write(curr_line)
# end with
if __name__ == '__main__':
main(sys.argv)
and here's a shell script driver:
#!/bin/bash
tmp="$(mktemp /tmp/asciidoc-cleanup.XXXXXX)"
for file in *.txt ; do
./asciidoc.py $file > $tmp
if [[ $? == 0 ]]; then
mv $tmp $file
else
echo "error in $file" >&2
fi
done
YMMV, etc.
Hope this helps!
On Tue, Sep 19, 2017 at 12:23 PM, Stephen Mallette <[email protected]>
wrote:
> For whatever reason we started writing our headers in our docs with:
>
> Header
> ======
>
> Subheader
> ---------
>
> SubSubHeader
> ~~~~~~~~~~~~
>
> as opposed to the alternative:
>
> = This Is A Header
>
> == Subheader
>
> === SubSubHeader
>
> The downside with the first approach is that it forces us to do two things:
>
> 1. Remember the syntax for each header layer (which we all probably know
> pretty well at this point, but still...)
> 2. Ensure that the width of the header formatting line is equal to the
> length of the text above it.
>
> That second point is a killer sometimes. While I've trained myself to be
> good at noticing that problem I know it's bitten us in releases over and
> over and over again.
>
> Anyway, I think going to the alternative formatting would be better and
> propose to do a full reformatting. Please let me know if there are any
> concerns about doing that - if I don't hear back in the next few days I'll
> proceed with the changes.
>
> Thanks,
>
> Stephen
>
