Learn more about these different git repos.
Other Git URLs
I'm working on converting the Packaging Guidelines to git + asciidoc (in the latest approach), FPC ticket https://pagure.io/packaging-committee/issue/727.
My WIP is at: - https://in.waw.pl/~zbyszek/packaging-guidelines-adoc/packaging/ - https://pagure.io/fork/zbyszek/packaging-guidelines/branch/asciidoc
I have some issues which I might be approaching in a totally wrong way, so I'd appreciate some pointers:
1. syntax highlighting
I use the following format:
[source,spec] .... %build an example here ....
In some cases this seems to work, but not when spec is the language.
spec
I have :source-highlighter: pygments at the top of the document, and the result (for example https://in.waw.pl/~zbyszek/packaging-guidelines-adoc/packaging/Ada.html) is not highlighted, even though pygmentize -l spec ... on a temporary file with the same snippet works just fine.
:source-highlighter: pygments
pygmentize -l spec ...
2. formatting
Ada source files in -devel packages (*.ads and *.adb) MUST be placed in the %{_includedir}
Asciidoc seems to require unpredictable sequences of escaping. In particular, to get the above example to display properly I used:
packaging/Ada.adoc:* Ada source files in -devel packages (`\*.ads` and `*.adb`) *MUST* be placed in the `%{_includedir}` directory or a subdirectory thereof.
(note that the star before "adb" is not escaped). What is the proper way to include "code", i.e. stuff that has various special formatting characters embedded?
3. hyperlinks
I want to have many many hyperlinks between various pages. When linking within a page, I use the <<link-name>> stanza, and that gets replaced by a hyperlinked title of the link target. Perfect. But that doesn't seem to work across pages. How to achieve this? (I'm aware that it's possible to type the target page explicitly and copy the title, but that's error prone and complicated and does not update automatically...).
<<link-name>>
3a. bad links
I get no warnings about dead (internal) hyperlinks?
4. requirement to commit before rendering
This is rather inconvenient for interactive work, I end up doing git commit --amend -a --no-e all the time. Is there a way to tell asciibinder to just build whatever is in the working tree?
git commit --amend -a --no-e
I've put a build online at https://bex.fedorapeople.org/fpc/latest/packaging/Guidelines.html that shows the theming. If you add PRs to your pagure repo I'll send you a PR.
Re Questions:
Syntax Highlighting
Currently Asciidbinder uses coderay, not pygments. I believe we can write a simple patch to allow pygments so while this is blocked today it doesn't need to be in the future. The negative is it pulls in a python requirement. From upstream's perspective this is "bad" from our's this is "ok".
formatting
This is AsciiDoc. The first backslash is escaping the bold sequence that would be formed by the asterisks. It looks unpredictable because we are considering the asterisks to be unrelated by the parser doesn't.
I suggest always using the backslash. Alternately, you can surround the *.ads with single plus signs as +*.ads+ iirc.
hyperlinks
This doesn't work well today due to a decision made in AsciiBinder. There is ongoing discussion in the upstream about this. For now, we have to use proper links.
commit before rendering
This should be happening. I modified your _distro_map.yml to reference the asciidoc branch and it just built with my uncommitted code.
There is a hard requirement that the repo must have at least one commit in it.
I've put a build online at https://bex.fedorapeople.org/fpc/latest/packaging/Guidelines.html that shows the theming.
If you add PRs to your pagure repo I'll send you a PR.
It should be on now.
Re Questions: Syntax Highlighting Currently Asciidbinder uses coderay, not pygments. I believe we can write a simple patch to allow pygments so while this is blocked today it doesn't need to be in the future. The negative is it pulls in a python requirement. From upstream's perspective this is "bad" from our's this is "ok".
That explains the issue. Looking at http://www.rubydoc.info/gems/coderay/CodeRay/FileType, coderay simply does not support .spec. Some common useful types that seem to be missing would be python3 (different keywords than python2), pycon (i.e. a transcript with >>> lines), and "console" (i.e a transcript with $ prompt lines). So it seems that it would be worth switching to a different highlighter.
formatting This is AsciiDoc. The first backslash is escaping the bold sequence that would be formed by the asterisks. It looks unpredictable because we are considering the asterisks to be unrelated by the parser doesn't. I suggest always using the backslash. Alternately, you can surround the .ads with single plus signs as +.ads+ iirc.
That seems to work nicely, thanks.
hyperlinks This doesn't work well today due to a decision made in AsciiBinder. There is ongoing discussion in the upstream about this. For now, we have to use proper links.
Hmmm.
commit before rendering This should be happening. I modified your _distro_map.yml to reference the asciidoc branch and it just built with my uncommitted code.
Hmm, it says "Stashing uncommited changes and files in working branch". But then it pops the stash... It's a bit confusing, but you are right that the unstages changes are included in the build.
I've opened a ticket in the upstream about the highlighter here: https://github.com/redhataccess/ascii_binder/issues/136
I suspect a ruby programmer could help with modifying this to do an "opportunistic" enablement so that we don't bloat the requirements set. I am out of cycles at the moment, but this is only one of several potential changes like this so I hope it will get some help soon.
re: hyperlinks
This is the second significant use of these that hasn't been corrected inline I've had. I am anxious to get this fixed for lots of reasons. I have a strategy and no time. Again, it is probably a relatively basic ruby lang task to write a preprocessor to fix these while upstream thinks about the long term strategy.
re: git messages
yep - it does that :)
I'll try to get you a PR today.
There appears to be a Pagure bug/feature that prevents me from sending you a PR @zbyszek
Would you be willing to add me (@bex) as a commiter on your fork and I'll do it there.
I am going to open a pagure issue on this.
@fale - I sent two PRs to the main packaging guidelines repo. I can't access them to close them. Can you?
@bex: No, I can not close them since I guess there is a bug we hit. Also it seems like there is a bug that prevent me to add you as admin :/
Bug filed: https://pagure.io/pagure/issue/2964
I added @bex as admin, but I still see the message "The permissions on this repository are being updated. This may take a while. During this time, you or some of the project's contributors may not be able to push to this repository.", continuously since I created the repo a few days ago. So YMMV.
BTW., @fale I asked for privileges on your repo to, by mail, a few days back. Not sure if you got it, so I'm asking here again.
@zbyszek I noticed that about your repo too but assumed you were messing around with permission :). I strongly encourage you to note this in the pagure bug issue I opened and to open and infra ticket to your repo "looked at"
I managed to be able to give both @bex and @zbyszek admin acces :)
@zbyszek I am worried that I am blocking you on this - ignoring our pagure challenges, do you have what you need from me at this moment?
I was just working locally. I spent quite a bit of time fixing links and formatting issues. I hoped to do this for all pages in the Guidelines, but it's more work than I expected. So my plan now is polish ~10 pages, and for the rest just do the automatic conversion and basic link fixing. I hope other people can pick up the rest and do the fixing if/when it is decided that this is the route the FPC wants to take.
I'll push my changes to fale's old repo, and I hope you can push the PR you couldn't submit before there.
@zbyszek perfect - just ping me when I need to rebase my pr
Login to comment on this ticket.