Re: [zeromq-dev] Linux build help?

[Axel R.]

Nvm the PR has been rejected. I was hoping my source-code annotation
initiative would be given more thoughtful consideration.

On Tue, Oct 24, 2023 at 10:38 AM Axel R.  wrote:

> Yep the PR is up for review. It was indeed a trivial issue, there was a
> file under packaging/ that needed the new file listed and the Linux builds
> started working.
>
> I have one more trivial issue where a file locally formatted with
> clang-format -I --style=file doesn’t pass the formatting test on the online
> build.
>
> For some reason the local convention appears to mandate spaces before
> opening parentheses as in MACRO (x) or __attribute (x) which is not
> aligned with most C and C++ formatting rules of the world, where a space
> precedes a parenthesis only after language keywords.
>
> The existing code isn’t conforming strictly to the .clang-format file that
> is checked-in with the project. Some of the existing files change if I run
> clang-format on them with that formatting file, and spaces get added before
> some of the few existing parentheses that don’t have one already (e.g.
> __declspec(dllimport) in zmq.h)
>
> The clang-* build targets created by CMake on Windows fail because they
> call chmod for some reason, so I suspect a new .clang-format file does not
> get created? But why is it needed to set write attributes on existing files
> during builds? And why any build artefact was checked-in (if that is the
> case that .clang-format is supposed to be generated)
>
> There should not be so much frictions around minor formatting
> discrepancies. I think this nonstandard spacing policy should be abrogated.
>
> “Put a space before an open parenthesis only in control flow statements,
> but not in normal function call expressions and function-like macros.”
> https://llvm.org/docs/CodingStandards.html
>
> This is aligned with most formatting conventions back to the original K
> and I think this project should return to that instead of standing out in a
> nonstandard way, and the formatting rules file should be checked-in and not
> generated as it does not work on all platforms today (unless there is a
> compelling reason to create that file during builds?)
>
> Thoughts?
>
> —Axel
>
>
> Sent from my iPhone
>
> On Oct 24, 2023, at 04:05, Arnaud Loonstra  wrote:
>
> Seems a trivial problem. Have you created the PR already?
>
> On 22/10/2023 10:04, Axel R. wrote:
>
> Hi, I'm trying to submit a PR, but the Linux builds fail. I added a new
> include\zmq_sal.h next to include\zmq.h and #included it as "zmq_sal.h"
> from zmq.h, which builds locally on Windows as well as on Github. However,
> the Linux builds fails ("../../src/../include/zmq.h:34:10: fatal error:
> zmq_sal.h: No such file or directory") I tried  #include  to no
> avail. Any idea? How was zmq_utils.h included?
>
>
> ___
>
> zeromq-dev mailing list
>
> zeromq-dev@lists.zeromq.org
>
> https://lists.zeromq.org/mailman/listinfo/zeromq-dev
>
> ___
> zeromq-dev mailing list
> zeromq-dev@lists.zeromq.org
> https://lists.zeromq.org/mailman/listinfo/zeromq-dev
>
>
___
zeromq-dev mailing list
zeromq-dev@lists.zeromq.org
https://lists.zeromq.org/mailman/listinfo/zeromq-dev

Re: [zeromq-dev] [zeromq/libzmq] Introduce SAL2 annotations (PR #4605)

[Axel R.]

I need to understand how things work here before I can consider suggesting using this library. I sent mail to this list proposing to add SAL annotations to the codebase in phases, and the feedback I got was that it was welcome.The subsequent PR got a few laconic comments that were not much aligned with what I’d consider to be respectful and constructive feedback.For example asking me to “go ask the owner” of this “proprietary tool” - which is actually a compiler feature - to “make it work without needing to make a mess” after stating that they “would not read anything” as far as the related documentation is not the kind of feedback I expected.I need to convince myself that this community is still 1) welcoming new contributors and 2) keeping an open mind with regards to the evolution of the codebase.As it stands, I see two major adoption blockers as far as I’m concerned:a) There is no way to demonstrate correctness of both API usage and internal implementation. For example zmq::ip_addr_t zmq::ip_addr_t::any (int family_) happily returns uninitialized memory if passed an invalid parameter. SAL is meant to catch those (and much more) at compile time.b) The library takes on itself to terminate the process on runtime errors where it should never (like out of memory) and fail to terminate it on obvious programmer errors like the one above. In some contexts, a library terminating its calling process on runtime errors is a strict no-no. For example, a caller may elect to retry on ENOMEM after shrinking a cache or something. Anecdotally, using printf (which may allocates memory) to indicate an out of memory condition is also revealing of opportunities for improvement.I need to be sure that I can solve a) and b) and other potential blockers to a reasonable extent before investing more time on this project. Thoughts?—AxelOn Oct 24, 2023, at 03:44, Luca Boccassi  wrote:
Closed #4605.

—Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you authored the thread.Message ID: @github.com>
___
zeromq-dev mailing list
zeromq-dev@lists.zeromq.org
https://lists.zeromq.org/mailman/listinfo/zeromq-dev

Re: [zeromq-dev] Linux build help?

[Axel R.]

Yep the PR is up for review. It was indeed a trivial issue, there was a file 
under packaging/ that needed the new file listed and the Linux builds started 
working.

I have one more trivial issue where a file locally formatted with clang-format 
-I --style=file doesn’t pass the formatting test on the online build.

For some reason the local convention appears to mandate spaces before opening 
parentheses as in MACRO (x) or __attribute (x) which is not aligned with most C 
and C++ formatting rules of the world, where a space precedes a parenthesis 
only after language keywords.

The existing code isn’t conforming strictly to the .clang-format file that is 
checked-in with the project. Some of the existing files change if I run 
clang-format on them with that formatting file, and spaces get added before 
some of the few existing parentheses that don’t have one already (e.g. 
__declspec(dllimport) in zmq.h)

The clang-* build targets created by CMake on Windows fail because they call 
chmod for some reason, so I suspect a new .clang-format file does not get 
created? But why is it needed to set write attributes on existing files during 
builds? And why any build artefact was checked-in (if that is the case that 
.clang-format is supposed to be generated)

There should not be so much frictions around minor formatting discrepancies. I 
think this nonstandard spacing policy should be abrogated. 

“Put a space before an open parenthesis only in control flow statements, but 
not in normal function call expressions and function-like macros.” 
https://llvm.org/docs/CodingStandards.html

This is aligned with most formatting conventions back to the original K and I 
think this project should return to that instead of standing out in a 
nonstandard way, and the formatting rules file should be checked-in and not 
generated as it does not work on all platforms today (unless there is a 
compelling reason to create that file during builds?)

Thoughts?

—Axel


Sent from my iPhone

> On Oct 24, 2023, at 04:05, Arnaud Loonstra  wrote:
> 
> Seems a trivial problem. Have you created the PR already?
> 
>> On 22/10/2023 10:04, Axel R. wrote:
>> Hi, I'm trying to submit a PR, but the Linux builds fail. I added a new 
>> include\zmq_sal.h next to include\zmq.h and #included it as "zmq_sal.h" from 
>> zmq.h, which builds locally on Windows as well as on Github. However, the 
>> Linux builds fails ("../../src/../include/zmq.h:34:10: fatal error: 
>> zmq_sal.h: No such file or directory") I tried  #include  to no 
>> avail. Any idea? How was zmq_utils.h included?
>> 
>> ___
>> zeromq-dev mailing list
>> zeromq-dev@lists.zeromq.org
>> https://lists.zeromq.org/mailman/listinfo/zeromq-dev
> ___
> zeromq-dev mailing list
> zeromq-dev@lists.zeromq.org
> https://lists.zeromq.org/mailman/listinfo/zeromq-dev
___
zeromq-dev mailing list
zeromq-dev@lists.zeromq.org
https://lists.zeromq.org/mailman/listinfo/zeromq-dev

Re: [zeromq-dev] ZeroMQ docs

[Francesco]

Hi Brett,


FWIW, I think it is very reasonable to accept some syntax change in
> order to migrate to a better supported document compiler and to gain the
> new functionality of readthedocs.  So, for whatever it may be worth, I
> take back my initial opinion to leave the API .txt files as-is.
>

Actually in my PR I'm proposing to rename all .txt files to .adoc to
clarify they use Asciidoc syntax. It's clearly the correct extension that
should be used according to Asciidoc online resources.
As per the content: I migrated them to use the more modern asciidoc syntax.


> Francesco, I know you have already invested effort down the asciidoctor
> path but maybe it is worth considering to jump fully to a flavor of
> markdown (eg github's)?
>

I'm not sure. Of course they're biased but Asciidoc community claims to be
better and a "more sound alternative" to Markdown, see:
   https://docs.asciidoctor.org/asciidoc/latest/asciidoc-vs-markdown/

A less-biased comparison (much longer to read -- I didn't read it all) is
at:
  https://www.dewanahmed.com/markdown-asciidoc-restructuredtext/


Actually, when I
> started writing I half assumed they were in markdown and half assumed
> they were in some special markdown'ish GSL syntax and only later figured
> out they were asciidoc.  But then I got confused about how to compile them
> (ie,
> asciidoc-py vs asciidoctor that you described).  Certainly, my stumbles
> were due to my ignorance/assumptions but had the docs been in markdown,
> all these little frictions would not have shown up.  Again, opinion fwiw.
>
I totally agree.
I also contributed some fixes/new features in the past and documenting them
was tricky. The .txt extension does not help at all.
The use of archaic tools makes it very hard to the "casual" contributor to
see the actual documentation rendered.
Even more tricky: I was expecting api.zeromq.org to automatically get
updated after some time the PR was merged... I discovered it's not the case
:)

Last but not least: my use case for spending a few hours on this PR /
documentation improvement was very simple: I noticed a very nice new option
(ZMQ_BUSY_POLL) in the release notes. Then I started to search for docs to
share with the rest of the teams. I found only the .txt version, nothing I
could easily link in an email or share with simplicity... that was the
trigger point... :)


Thanks,
Francesco
___
zeromq-dev mailing list
zeromq-dev@lists.zeromq.org
https://lists.zeromq.org/mailman/listinfo/zeromq-dev

Re: [zeromq-dev] ZeroMQ docs

[Brett Viren]

Francesco  writes:

> Update: apparently the point a) is blocked by point b).
>
> In more details:  the Asciidoc modern syntax to get a cross-reference
> correctly rendered in both manpages and HTMLs is:
>
>  xref:name_of_doc.adoc[name_of_doc]

FWIW, I think it is very reasonable to accept some syntax change in
order to migrate to a better supported document compiler and to gain the
new functionality of readthedocs.  So, for whatever it may be worth, I
take back my initial opinion to leave the API .txt files as-is.

Francesco, I know you have already invested effort down the asciidoctor
path but maybe it is worth considering to jump fully to a flavor of
markdown (eg github's)?

Given the similarity between asciidoctor and markdown syntax, this
change would not be so large for both human editors and the
mass-replacement you are developing.  The additional benefit is that
having the API docs in markdown syntax would give libzmq more options
for building end-user document formats.

I guess these docs will not see much change going forward but as someone
who recently contributed a new one I can say that process would have
been easier if the API docs were in markdown format.  Actually, when I
started writing I half assumed they were in markdown and half assumed
they were in some special markdown'ish GSL syntax and only later figured
out they were asciidoc.  But then I got confused about how to compile them (ie,
asciidoc-py vs asciidoctor that you described).  Certainly, my stumbles
were due to my ignorance/assumptions but had the docs been in markdown,
all these little frictions would not have shown up.  Again, opinion fwiw.

-Brett.
___
zeromq-dev mailing list
zeromq-dev@lists.zeromq.org
https://lists.zeromq.org/mailman/listinfo/zeromq-dev

Re: [zeromq-dev] Linux build help?

[Arnaud Loonstra]

Seems a trivial problem. Have you created the PR already?

On 22/10/2023 10:04, Axel R. wrote:
Hi, I'm trying to submit a PR, but the Linux builds fail. I added a 
new include\zmq_sal.h next to include\zmq.h and #included it as 
"zmq_sal.h" from zmq.h, which builds locally on Windows as well as on 
Github. However, the Linux builds fails 
("../../src/../include/zmq.h:34:10: fatal error: zmq_sal.h: No such 
file or directory") I tried  #include  to no avail. Any 
idea? How was zmq_utils.h included?


___
zeromq-dev mailing list
zeromq-dev@lists.zeromq.org
https://lists.zeromq.org/mailman/listinfo/zeromq-dev

___
zeromq-dev mailing list
zeromq-dev@lists.zeromq.org
https://lists.zeromq.org/mailman/listinfo/zeromq-dev

Re: [zeromq-dev] *** SPAM *** Re: ZeroMQ docs

[Francesco]

Hi Fabrice,
Thanks for the pointer.
Pandoc however seems to be able to convert only _to_ Asciidoc, not _from_
Asciidoc (by looking at https://pandoc.org/).
Anyway, thanks to some regex I managed to upgrade the format of the
Asciidoc documentation from the legacy format to the "modern/current"
Asciidoc format.

I have updated the PR at https://github.com/zeromq/libzmq/pull/4607
Documentation rendered as Github Pages in my own fork:
https://f18m.github.io/libzmq/

Any comment is welcome

Thanks,
Francesco


Il giorno mar 24 ott 2023 alle ore 09:20 Fabrice Bacchella <
fabrice.bacche...@orange.fr> ha scritto:

> Did you try pandoc ?
>
> Le 23 oct. 2023 à 23:16, Francesco  a écrit
> :
>
> Update: apparently the point a) is blocked by point b).
>
> In more details:  the Asciidoc modern syntax to get a cross-reference
> correctly rendered in both manpages and HTMLs is:
>
>  xref:name_of_doc.adoc[name_of_doc]
>
> This will produce a valid link to "name_of_doc.html" for HTML output and a
> simple "name_of_doc" span of text for manpage output. This is the fix
> mentioned in step a).
> However this syntax is accepted only when Asciidoctor is NOT running in
> legacy/deprecated mode.
> To avoid that, I first need step b).
>
> Shall I put steps a) and b) together in my same WIP PR ?
> It will be harder to review it...
>
> thanks
>
>
> Il giorno lun 23 ott 2023 alle ore 22:43 Francesco <
> francesco.monto...@gmail.com> ha scritto:
>
>> Hi all,
>>
>> Here's an update on my attempt to refresh the doc system for libzmq API.
>>
>> *Current status:*
>>   libzmq is built around the "ancient" python Asciidoc tool. That tool is
>> unmaintained for several years and has been replaced by the Asciidoctor
>> tool (see
>> https://docs.asciidoctor.org/asciidoctor/latest/migrate/asciidoc-py/).
>>   Note that the original tool used for interpreting the .txt files was
>> named "asciidoc" just like the language markup contained in the .txt files
>> itself. To avoid confusion, that tool is now referred to as "asciidoc-py".
>>   The tool asciidoc-py is the one unmaintained. The language Asciidoc
>> itself instead is still maintained and developed, but Asciidoctor is the
>> only updated tool to process Asciidoc documents.
>>   The manpages are built today in libzmq through this chain:
>>   .txt  --[asciidoc]-->   .xml docbook--[xmlto]-->.3 or .7
>> manpages
>>   where the [] indicate the tool used for the conversion. Also the
>> utility "xmlto" seems quite unmaintained.
>>   Finally the wikidot website http://api.zeromq.org/ is built from some
>> scripts located in the "ztools" repo that basically leverages the ability
>> of that wiki to produce a listing of all wiki pages uploaded by group; the
>> group used is the ZMQ API version. This makes it possible to document
>> multiple versions of the libzmq API in the same website/wiki. However
>> wikidot itself seems unmaintained as well.
>>
>> *Where I got so far:*
>>   I managed to convert to obtain usable and nicely-formatted HTML docs
>> running Asciidoctor on libzmq docs, after some mass-replacement passes to
>> fix some syntax issues.
>>   Asciidoctor is still processing all libzmq docs using the so-called
>> "compatibility mode".
>>  In my libzmq fork I enabled Github pages and I got them deployed on
>> every checkin of my branch.
>>  Documentation rendered as Github Pages in my own fork:
>> https://f18m.github.io/libzmq/
>>  PR: https://github.com/zeromq/libzmq/pull/4607
>>
>> *Next steps:*
>>   a) I'm fighting a little bit with Asciidoctor to get the right
>> rendering also for manpages.
>>   b) Some smart mass-replace is still needed to convert from the
>> deprecated Asciidoc format to the "modern" Asciidoc (see
>> https://docs.asciidoctor.org/asciidoctor/latest/migrate/asciidoc-py/#updated-and-deprecated-asciidoc-syntax
>> )
>>   c) The Github pages approach is able to deploy only the documentation
>> for the latest "master" branch. Maintaining documentation for the multiple
>> API versions is probably best achieved using the more popular
>> readthedocs.io. As pointed out already in this email thread,
>> readthedocs.io is mostly designed around Sphinx and MkDocs but most
>> recent versions are flexible enough to accomodate also Asciidoc
>> documentation. I think eadthedocs.io is the best solution to store
>> different versions of libzmq API.
>>
>> Please let me know if you have any comments.
>> In my opinion to simplify the PR review, after step a) it's best to do a
>> first merge, and then carry out points b) and c) in 2 more separate PRs.
>>
>> What do you think?
>>
>> Thanks,
>>
>>
>>
>> Il giorno ven 20 ott 2023 alle ore 18:19 Brett Viren <
>> brett.vi...@gmail.com> ha scritto:
>>
>>> On Fri, Oct 20, 2023 at 12:03 PM Francesco 
>>> wrote:
>>> >
>>> > Maybe an even simpler solution is to activate the Github "Pages"
>>> support in libzmq.org and link it with a github action that just uses
>>> the Asciidoctor generator to convert all of doc/*.txt into static HTML.
>>> >

Re: [zeromq-dev] *** SPAM *** Re: ZeroMQ docs

[Fabrice Bacchella]

Did you try pandoc ?

> Le 23 oct. 2023 à 23:16, Francesco  a écrit :
> 
> Update: apparently the point a) is blocked by point b).
> 
> In more details:  the Asciidoc modern syntax to get a cross-reference 
> correctly rendered in both manpages and HTMLs is:
> 
>  xref:name_of_doc.adoc[name_of_doc]
> 
> This will produce a valid link to "name_of_doc.html" for HTML output and a 
> simple "name_of_doc" span of text for manpage output. This is the fix 
> mentioned in step a).
> However this syntax is accepted only when Asciidoctor is NOT running in 
> legacy/deprecated mode.
> To avoid that, I first need step b). 
> 
> Shall I put steps a) and b) together in my same WIP PR ? 
> It will be harder to review it...
> 
> thanks
> 
> 
> Il giorno lun 23 ott 2023 alle ore 22:43 Francesco 
> mailto:francesco.monto...@gmail.com>> ha 
> scritto:
>> Hi all,
>> 
>> Here's an update on my attempt to refresh the doc system for libzmq API.
>> 
>> Current status:
>>   libzmq is built around the "ancient" python Asciidoc tool. That tool is 
>> unmaintained for several years and has been replaced by the Asciidoctor tool 
>> (see https://docs.asciidoctor.org/asciidoctor/latest/migrate/asciidoc-py/). 
>>   Note that the original tool used for interpreting the .txt files was named 
>> "asciidoc" just like the language markup contained in the .txt files itself. 
>> To avoid confusion, that tool is now referred to as "asciidoc-py". 
>>   The tool asciidoc-py is the one unmaintained. The language Asciidoc itself 
>> instead is still maintained and developed, but Asciidoctor is the only 
>> updated tool to process Asciidoc documents.
>>   The manpages are built today in libzmq through this chain:
>>   .txt  --[asciidoc]-->   .xml docbook--[xmlto]-->.3 or .7 
>> manpages
>>   where the [] indicate the tool used for the conversion. Also the utility 
>> "xmlto" seems quite unmaintained.
>>   Finally the wikidot website http://api.zeromq.org/ is built from some 
>> scripts located in the "ztools" repo that basically leverages the ability of 
>> that wiki to produce a listing of all wiki pages uploaded by group; the 
>> group used is the ZMQ API version. This makes it possible to document 
>> multiple versions of the libzmq API in the same website/wiki. However 
>> wikidot itself seems unmaintained as well.
>> 
>> Where I got so far:
>>   I managed to convert to obtain usable and nicely-formatted HTML docs 
>> running Asciidoctor on libzmq docs, after some mass-replacement passes to 
>> fix some syntax issues. 
>>   Asciidoctor is still processing all libzmq docs using the so-called 
>> "compatibility mode". 
>>  In my libzmq fork I enabled Github pages and I got them deployed on every 
>> checkin of my branch.
>>  Documentation rendered as Github Pages in my own fork: 
>> https://f18m.github.io/libzmq/ 
>>  PR: https://github.com/zeromq/libzmq/pull/4607
>> 
>> Next steps:
>>   a) I'm fighting a little bit with Asciidoctor to get the right rendering 
>> also for manpages.
>>   b) Some smart mass-replace is still needed to convert from the deprecated 
>> Asciidoc format to the "modern" Asciidoc (see 
>> https://docs.asciidoctor.org/asciidoctor/latest/migrate/asciidoc-py/#updated-and-deprecated-asciidoc-syntax)
>>   c) The Github pages approach is able to deploy only the documentation for 
>> the latest "master" branch. Maintaining documentation for the multiple API 
>> versions is probably best achieved using the more popular readthedocs.io 
>> . As pointed out already in this email thread, 
>> readthedocs.io  is mostly designed around Sphinx and 
>> MkDocs but most recent versions are flexible enough to accomodate also 
>> Asciidoc documentation. I think eadthedocs.io  is the 
>> best solution to store different versions of libzmq API.
>> 
>> Please let me know if you have any comments.
>> In my opinion to simplify the PR review, after step a) it's best to do a 
>> first merge, and then carry out points b) and c) in 2 more separate PRs.
>> 
>> What do you think?
>> 
>> Thanks,
>> 
>> 
>> 
>> Il giorno ven 20 ott 2023 alle ore 18:19 Brett Viren > > ha scritto:
>>> On Fri, Oct 20, 2023 at 12:03 PM Francesco >> > wrote:
>>> >
>>> > Maybe an even simpler solution is to activate the Github "Pages" support 
>>> > in libzmq.org  and link it with a github action that 
>>> > just uses the Asciidoctor generator to convert all of doc/*.txt into 
>>> > static HTML.
>>> >
>>> > What do you think about this?
>>> 
>>> This sounds like a very good idea to me.  And, it's even easier as the
>>> existing libzmq build already produces the HTML.
>>> 
>>> On could prototype some additional build action that populate the
>>> special gh-pages by committing these generated HTML files.  This can
>>> be tested using a personal fork of libzmq to make your own
>>> https://.github.io/libzmq/