Re: Installing nokogiri with --use-system-libraries (was: Re: Migrating the guide to AsciiDoc)

[Mojca Miklavec]

Hi,

On 23 April 2018 at 17:42, Rainer Müller wrote:
>
> Ruby and gems are really strange...
>
> Apparently, installing nokogiri with bundle fails

Wasn't it you who said that we don't need a port for it as it's just a
one-time conversion? :)
(I'm honestly not sure who said that.)

Looking at how elegant the asciidoctor port is ... I still believe we
should make a port for docbookrx.
(I guess someone first needs to document how to use a ruby portgroup,
so we need to get the conversion to asciidoc done first, right? :) :)
:)

> Here is a way to get it working:
>
> $ git clone https://github.com/asciidoctor/docbookrx
> $ cd docbookrx
> $ sudo port install rb23-bundler
> $ bundle-2.3 config --local build.nokogiri --use-system-libraries 
> --with-xml2-dir=/opt/local --with-xml2-include=/opt/local/include/libxml2 
> --with-xslt-dir=/opt/local --with-zlib-dir=/opt/local 
> --with-exslt-dir=/opt/local --without-pkg-config
> $ bundle-2.3 install --path=.bundle/gems

Installing gems is a genuinely error-prone process on Mac, you can
find lots and lots of reports of broken behaviour and they are not
always responsive, sometimes deleting comments from tickets etc.

One example (which eventually got fixed, but there are a number of those):
https://github.com/sparklemotion/nokogiri/issues/1423
(I would have linked to another ticket, but my comments were boldly deleted.)

I was initially following this procedure:
https://gorails.com/setup/osx/10.13-high-sierra
basically
sudo port install rbenv ruby-build
(which should be up to date) and then installed bundler with rbenv.
For once, it magically worked and I was surprised since I've been
fighting with issues for years (on admittedly an older OS).

I have huge philosophical problems with this line:
--use-system-libraries --with-xml2-dir=/opt/local
--with-xml2-include=/opt/local/include/libxml2
--with-xslt-dir=/opt/local --with-zlib-dir=/opt/local
--with-exslt-dir=/opt/local
because this will lead to broken software as soon as one updates some
libraries under MacPorts. (Does HomeBrew ever delete old versions or
do their old versions of libraries remain installed forever until the
user removes them?)

I did not use any of those workarounds this time for once (I didn't
use external libraries).

You'll get an impression about the quality of the build system by
reading this (copy-pasted at the bottom) as "reference installation
instructions":
http://installrails.com/steps/install_rails

> Then go to the guide/xml/ directory of macports-guide:
>
> $ BUNDLE_GEMFILE=~/src/docbookrx/Gemfile bundle-2.3 exec docbookrx guide.xml
> $ mv *.adoc ../adoc/

I eventually managed to use
~/app/docbookrx/bin/docbookrx guide.xml
but I also didn't manage to make docbookrx a simple executable that I
could put or symlink into PATH.

On 24 April 2018 at 00:23, Rainer Müller wrote:
> On 2018-04-23 20:35, Andrew Moore wrote:
>> You might try:
>>
>> $ sudo gem update —system
>>
>> which should install the latest version of bundler (you really want that), 
>> and go from there.
>> In the particular case of nokogiri, you might also try running `gem install 
>> nokogiri` as user root.
>
> I am very cautious about running third-party package managers as root
> and let them write to ${prefix}. That is supposed to be managed by
> MacPorts and no other package manager should update files.

B  no!!!
Why "sudo gem"? This sounds like a terrible idea. You should
absolutely install gems locally, not as sudo, and in particular not
under /opt/local.

Mojca


PS: Quotation from http://installrails.com/steps/install_rails:

If Rails cannot install, check the failure message. if it contains:

-
libxml2 is missing.  Please locate mkmf.log to investigate how it
is failing.
-

and you are using OS X 10.10 or later, then run:

brew install libxml2
env ARCHFLAGS="-arch x86_64" gem install nokogiri:1.6.4.1 --
--use-system-libraries --with-xml=/usr/local/Cellar/libxml2/

to install libxml2 and nokogiri and rerun the rails instalation.

Else, try running the code below and then restarting your computer:

brew install apple-gcc42

Re: Gsoc 18 Project | Collect build statistics

[Jackson Isaac]

Hi Vishnu,

Welcome to The MacPorts Project!

On Tue, Apr 24, 2018 at 4:15 AM, Vishnu  wrote:
> Hey,
>
> So first thing.
> (a.1) I am planning to install ubuntu on my pc in a day.
> I guess We can install Macports on that.

That's great. Let us know if you face any issues and if we could be of any help.

I was also thinking about cloud platform (specifically Google Cloud) which gives
you around 300$ of credits for one year where you could spin up a VM and test
the installation.

Note: It might need a Credit Card for authentication.

> (a.2 , a.3) Once macports is installed i'll install mpstats ,buildbot too.
>
> (b.1) I went and completed week 1.But i am unable to access week 3 , week
> 4.Because the course starts on April 30 i guess.
> I went through the topics.
> Week 3 : Subqueries and Join
> Week 4 : Modifying and Analyzing Data with SQL
>

I guess you can join the upcoming session and complete all the
assignments and weeks
before hand too (I was able to do so few weeks back).

> So now would learn more about these topics through youtube, many other
> resources.
>
> (b.2) Will look into them.
> (b.3) Django hopefully wouldn't be a problem.
>
> (c.0)  I would suggest that we create a new repository for your project
> under
> MacPorts, you fork it and use your own fork for endlessly playing with
> it, testing etc
> This sounds good.
> I think i would be more comfortable with Github.
>
> (c.2) Can be done.
> (c.3) You are talking about Build History data ..right?
> There is already a JSON API for it as you said..so cant we use it? (
> https://build.macports.org/json/help )
>
> (d.1 , d.2) Yes will do the research .
>
>
> (e.1) I think when i will be changing Buildbot to update the database after
> every build ..Then i would need Tcl.
> Will learn them as i get time.
>

Speaking from experience, I would suggest go through the basics of Tcl
and write some small sample programs to get the gist of Tcl.
This would help you recall whatever you tried now at a later point
of time when you actually touch macports-base.

https://www.tcl.tk/man/tcl8.5/tutorial/Tcl0.html helped me a lot.
I always keep this window open while developing base.

> Will see Project Description.
>
> Also i have my Semester End exams from 27 April - 7 may.
> So maybe i would not be able to reply on time.
>

No issues. Do well for the exams :) Keep us updated.

Looking forward to a great summer this year :)

-- 
Jackson Isaac

Re: Installing nokogiri with --use-system-libraries (was: Re: Migrating the guide to AsciiDoc)

[Andrew Moore]

On Apr 23, 2018, at 6:23 PM, Rainer Müller  wrote:
> 
> On 2018-04-23 20:35, Andrew Moore wrote:
>> You might try:
>> 
>> $ sudo gem update —system
>> 
>> which should install the latest version of bundler (you really want that), 
>> and go from there.
>> In the particular case of nokogiri, you might also try running `gem install 
>> nokogiri` as user root.
> 
> I am very cautious about running third-party package managers as root
> and let them write to ${prefix}. That is supposed to be managed by
> MacPorts and no other package manager should update files.
> 
> If this overwrites any file provided by the ruby port, just running
> a deactivate/activate cycle will bring back the old version. Or an
> inconsistent state, if it also wrote new files to keep the version
> information.
> 
> If there is ever going to be a rb23-nokogiri port, I expect this to
> cause conflicts later with files not known to MacPorts.
> 
> When I uninstall the ruby port, this might leave traces behind
> in ${prefix} that can be cleaned up, but I would not be aware of that.
> 
> nokogiri uses vendored versions of zlib/libxml2/libxslt and other
> dependencies by default. I already have them installed in ${prefix}
> and I do not want to build them again from source, therefore I used
> --use-system-libraries (as the README of docbookrx suggested).
> 
> I even dared to give this a try as root (again, not recommended),
> but this also fails in the same way:
> 
> $ sudo gem2.5 install nokogiri -- --use-system-libraries
> ...
> pkg-config could not be used to find libxml-2.0
> ...
> 
> From .../mkmf.log:
> 
> "pkg-config --exists libxml-2.0"
> dyld: Symbol not found: __cg_jpeg_resync_to_restart
>  Referenced from: 
> /System/Library/Frameworks/ImageIO.framework/Versions/A/ImageIO
>  Expected in: /opt/local/lib/libJPEG.dylib
> in /System/Library/Frameworks/ImageIO.framework/Versions/A/ImageIO
> package configuration for libxml-2.0 is not found
> 
> This pkg-config command works fine outside of 'gem install'.
> 
> The crash report in Console.log shows that the invocation of pkg-config
> included the environment variable: DYLD_LIBRARY_PATH=.:/opt/local/lib

I do remember having to run as root user to get nokogiri to install at one time.
In particular, running as `sudo` was insufficient.  I’m guessing that it was a 
sandboxing
issue, but don’t recall the details, nor even the version of ruby involved. 
That shouldn’t be
necessary today, though Nokogiri has been problematic to install at times over 
the years.

I'll start right now trying to hunt the problem down,  with a vanilla Install 
of MacPorts on
a macOS 10.12 system and MacPorts ruby 2.3.

I’ll just mention while on topic that ruby is developed on Linux, so macOS 
support can lag.
For instance, the current version of ruby-ffi works fine on *BSD, but not 
macOS, where  I have
to go back to an earlier version (1.9.21).
-AM

Re: [macports-ports] branch master updated: collectd: update to 5.8.0

[Perry E. Metzger]

On Tue, 24 Apr 2018 01:11:28 +0200 Rainer Müller
 wrote:
> There is a box with a "WARNING" near the end, but probably we should
> also place another one at the top.

I'd also recommend removing the "openmaintainer". :(

> > I'll go in now and try to fix what I damaged.  
> 
> No worries, I am looking into it. The update is long overdue anyway.

I've sent you a list privately with the list of plugins that are
apparently missing.

Perry
-- 
Perry E. Metzgerpmetz...@macports.org

Re: [macports-ports] branch master updated: collectd: update to 5.8.0

[Rainer Müller]

On 2018-04-24 00:48, Perry E. Metzger wrote:
> On Mon, 23 Apr 2018 23:58:23 +0200 Rainer Müller
>  wrote:
>> It is a bit suspicious that you made no changes to files/dep-gen.sh
>> in the port directory.
>>
>> The second half of the Portfile is fully generated by that shell
>> script, as collectd has *a lot* of variants for each of its
>> plugins. Updating that script is mostly manual work, based on the
>> output of './configure --help'. I somehow doubt that this version
>> of collectd does not have any new plugins or updated dependencies...
> 
> Apologies. I didn't see any instructions to that effect. Might I
> suggest that we remove this from being openmaintainer given that
> simple version bumps won't work well without inside knowledge?

There is a box with a "WARNING" near the end, but probably we should
also place another one at the top.

> I'll go in now and try to fix what I damaged.

No worries, I am looking into it. The update is long overdue anyway.

> (As for why I was playing with this, it's the only client of
> protobuf-c...)
Rainer

Re: Gsoc 18 Project | Collect build statistics

[Vishnu]

Hey,

So first thing.
(a.1) I am planning to install ubuntu on my pc in a day.
I guess We can install Macports on that.
(a.2 , a.3) Once macports is installed i'll install mpstats ,buildbot too.

(b.1) I went and completed week 1.But i am unable to access week 3 , week
4.Because the course starts on April 30 i guess.
I went through the topics.
Week 3 : Subqueries and Join
Week 4 : Modifying and Analyzing Data with SQL

So now would learn more about these topics through youtube, many other
resources.

(b.2) Will look into them.
(b.3) Django hopefully wouldn't be a problem.

(c.0)  I would suggest that we create a new repository for your project
under
MacPorts, you fork it and use your own fork for endlessly playing with
it, testing etc
This sounds good.
I think i would be more comfortable with Github.

(c.2) Can be done.
(c.3) You are talking about Build History data ..right?
There is already a JSON API for it as you said..so cant we use it? (
*https://build.macports.org/json/help
* )

(d.1 , d.2) Yes will do the research .


(e.1) I think when i will be changing Buildbot to update the database after
every build ..Then i would need Tcl.
Will learn them as i get time.

Will see Project Description.

Also i have my Semester End exams from 27 April - 7 may.
So maybe i would not be able to reply on time.

Thanks
Vishnu







On 24 April 2018 at 03:37, Mojca Miklavec  wrote:

> Dear Vishnu,
>
> I have a bunch of suggestions written below. Community bonding should
> usually be used to getting familiar with our codebase, our tools, our
> communication channels, getting to know people, ...
>
> Since you are creating a standalone product, this community bonding
> could be slightly different (not so much need to learn our base code
> by heart), but it should warm you up and get you up to full speed by
> the time the coding period starts.
>
> The most important parts are:
> - getting MacPorts installed somewhere where you have regular access
> - creating a repository and finish/improve the planning, I would like
> to see the database design finalized, finish the sample HTML document,
> ...
> - creating tickets with milestones
>
> I hope others will be able to comment on my suggestions (they are not
> universal truths :)
>
>
>
> INSTALLING MACPORTS, BUILDBOT
>
> (a.1) We explained that owning a Mac was not a requirement for working
> on this project, but it would be orders of magnitude easier to work on
> some tasks if you had a regular access to MacPorts. This could either
> be:
>   - SSH access to a remote Mac or VM
>   - A Linux machine (even if Raspberry PI) or a VM with Linux
>
> You should start working on this as soon as possible because it would
> be a pity to waste precious time during the coding period. MacPorts
> can theoretically be installed on a UNIX machine, but there might be
> problems of one kind or the other. We can help you circumvent the
> problems, but you need to star working on this ASAP.
>
> Please let us know what your plan is.
>
> (a.2) With MacPorts you should be able to install mpstats and use it
> to submit statistics (to either the official server or your new server
> once ready).
>
> (a.3) It would probably be quite helpful if you manage to install
> buildbot and replicate our setup (at least to some extent). But (a.1)
> is a strong requirement for that, else it makes no sense.
>
>
> SQL & OTHER TOOLS
>
> (b.1) This is an absolute must:
> https://www.coursera.org/learn/sql-for-data-science#
> along with some further understanding of primary keys, indices,
> foreign keys, ...
>
> Let us know whether you managed to subscribe and how you are
> progressing, whether you have any further questions etc.
>
> (b.2) I found two (fully optional) courses on web design:
> - a very lightweight one with very clear explanations and adorable
> teacher, good for listening to while going for a walk :)
>   https://www.coursera.org/learn/responsivedesign/
> - a more comprehensive one about bootstrap 4:
>   https://www.coursera.org/learn/bootstrap-4/
> You might know these things already and even if not, you probably know
> enough to come up with some basic styles for what we need; we don't
> need perfect design anyway.
>
> (b.3) Django (which you should know from inside out :)
>
>
> PLANNING
>
> (c.0) Open for discussion/suggestions ...
> I would suggest that we create a new repository for your project under
> MacPorts, you fork it and use your own fork for endlessly playing with
> it, testing etc. (No need to fork though, you can just start
> somewhere.) Once you think that part of your code is ready for review,
> you submit a pull request, we review it and merge it. That way we
> would end up with clean code upstream, all of it being properly
> reviewed.
>
> Once the code ends up in the MacPorts repository, that code should
> basically be ready for deployment.
>
> We use Trac as our main issue tracker. It depends on what others
> 

Re: [macports-ports] branch master updated: collectd: update to 5.8.0

[Rainer Müller]

On 2018-04-23 19:47, Perry E. Metzger wrote:
> Perry E. Metzger (pmetzger) pushed a commit to branch master
> in repository macports-ports.
>
> https://github.com/macports/macports-ports/commit/5b70112c367fdc957b751f1ca6b8f1d1314f3b46
>
> The following commit(s) were added to refs/heads/master by this push:
> new 5b70112 collectd: update to 5.8.0 5b70112 is described below
>
> commit 5b70112c367fdc957b751f1ca6b8f1d1314f3b46 Author: Perry E. Metzger 
> 
> AuthorDate: Mon Apr 23 13:47:10 2018 -0400
>
> collectd: update to 5.8.0 ---
>  sysutils/collectd/Portfile | 10 +-
>  1 file changed, 5 insertions(+), 5 deletions(-)
>
> diff --git a/sysutils/collectd/Portfile b/sysutils/collectd/Portfile
> index 589255c..978b1e6 100644 --- a/sysutils/collectd/Portfile +++
> b/sysutils/collectd/Portfile @@ -3,7 +3,7 @@  PortSystem  1.0
>  
>  namecollectd
> -version 5.7.2 +version 5.8.0  categories  sysutils net
>  platforms   darwin
>  license GPL-2
> @@ -20,10 +20,10 @@ homepage http://collectd.org/  master_sites
> http://collectd.org/files/
>  use_bzip2 yes
>  
> -checksums sha1 b27074fc363d942c8aee2f05baed0395a20c86d0 \ - sha256
> 9d20a0221569a8d6b80bbc52b86e5e84965f5bafdbf5dfc3790e0fed0763e592 \ -
> rmd160 81860b4fba7cf05b8eca19913ffe05d06b37e1a2 \ - size 1798777
> +checksums sha1 eb3567563de471e1950b7388e8883b911be3756a \ + sha256
> b06ff476bbf05533cb97ae6749262cc3c76c9969f032bd8496690084ddeb15c9 \ +
> rmd160 7b812b1046d57a9047213bb182b8744d98606547 \ + size 1686017  
>  depends_build   port:pkgconfig
>  

It is a bit suspicious that you made no changes to files/dep-gen.sh in
the port directory.

The second half of the Portfile is fully generated by that shell script,
as collectd has *a lot* of variants for each of its plugins. Updating
that script is mostly manual work, based on the output of './configure
--help'. I somehow doubt that this version of collectd does not have any
new plugins or updated dependencies...

Rainer

Re: Add a section on license names to the MacPorts guide?

[Ryan Schmidt]

On Apr 23, 2018, at 16:21, Perry E. Metzger wrote:
> On Mon, 23 Apr 2018 15:24:20 -0500 Ryan Schmidt wrote:
>> On Apr 23, 2018, at 14:19, Perry E. Metzger wrote:
>> 
>>> I'm thinking of adding the following to the MacPorts guide
>>> because we often have problems with people picking invalid
>>> license names in Portfile submissions.
>>> 
>>> That said, I'm not sure this is the best text for it. Thoughts?  
>> 
>> I don't want yet another copy of the list of valid licenses, to
>> become out of sync with the others. We already have them on a wiki
>> page.
> 
> I had no idea. What's the URL? I could change this to just point at
> that Wiki.

I was thinking of:

https://trac.macports.org/wiki/PortfileRecipes#license

and:

https://trac.macports.org/wiki/PortfileRecipes#licensekeyword

I'm in favor of moving documentation from the wiki, which I consider a 
temporary staging/play area, to the more permanent and refined Guide.

Re: Add a section on license names to the MacPorts guide?

[Perry E. Metzger]

On Mon, 23 Apr 2018 15:24:20 -0500 Ryan Schmidt
 wrote:
> On Apr 23, 2018, at 14:19, Perry E. Metzger wrote:
> 
> > I'm thinking of adding the following to the MacPorts guide
> > because we often have problems with people picking invalid
> > license names in Portfile submissions.
> > 
> > That said, I'm not sure this is the best text for it. Thoughts?  
> 
> I don't want yet another copy of the list of valid licenses, to
> become out of sync with the others. We already have them on a wiki
> page.

I had no idea. What's the URL? I could change this to just point at
that Wiki.

> If you want to *move* the list from the wiki page to the
> guide (leaving the wiki page essentially blank except for a link to
> the corresponding place in the guide), that would be great.

Either way is fine by me, I'll defer to everyone else.

> There was also talk at one point about switching from our somewhat
> custom license names to an official standard, such as
> https://spdx.org/licenses/, at which point we wouldn't need to keep
> our own list, but we're not there yet. (Is anybody working on that?)

That would be best of all, yes, and then we would just point at that.

Perry
-- 
Perry E. Metzgerpe...@piermont.com

Re: Gsoc 18 Project | Collect build statistics

[Mojca Miklavec]

Dear Vishnu,

Let me congratulate you for being accepted to the GSOC program with MacPorts.

Since your project is of vital importance for MacPorts, we will
require pretty high coding standards, including good documentation and
test cases, and strive towards early deployment, leaving sufficient
room for feedback and improvements.

Apart from regular email flow on the mailing list or IRC, I suggest to
have weekly live chat with mentors for brainstorming, ease of planning
& progress tracking, problem resolution, ...

We have three weeks of community bonding period in front of us. Making
good use of this time is equally important as coding itself, so we
hope you'll use this time well. I have a pretty long email nearly
ready with more instructions and suggestion about what I envisioned
for those three weeks. You might get some greeting from other members
of the team as well. You can expect help from me, Jackson and Umesh
(I'm at UTC+2, the other two are in the same time zone as you are),
but others should be able to help you as well (I don't always have all
the answers), final deployment can be done by Clemens or Rainer who
also have a lot more expertise in MacPorts internals than all the
three of us combined :).

We are looking forward to an awesome summer working together,
Mojca

Re: GSoC 2018: Congratulations to the selected student and mentors

[Vishnu]

Hello

I am overwhelmed by the results.
I would definitely keep in mind all the points mentioned by you.

Thanks

On Tue, Apr 24, 2018, 2:31 AM Umesh Singla 
wrote:

> Hello everyone,
>
> Google just announced 1,264 projects for this year's summer of code. I'm
> happy to share with you all that as requested MacPorts got one slot for the
> following project:
>
> 1. Vishnu M
> Project: Creating a dynamic website for Ports Index [1]
> Mentors: Mojca Miklavec and Jackson Isaac
>
> This goes without saying but I'm just reiterating:
>
> 1. I would like the student and the mentors to publicly interact with the
> community on the mailing list (preferably under a single thread) and IRC so
> that the rest of the community is able to follow the project and help you
> in case mentors go temporarily offline.
>
> 2. I would like the student and mentors to come up with a communication
> plan (how often do you want to meet, platform - mail/IRC/video) as soon as
> possible. This is really necessary so everyone has a clear idea from the
> beginning what to expect out of the project.
>
> This time until only the mid of May is meant for community bonding period,
> so learning any tools required or improving the project plan needs to be
> taken up before the official coding period begins.
>
> I hope others will add more to this email. I'll myself add more to this
> once my exams get over.
>
> Regards,
> Umesh
>
> [1]: https://summerofcode.withgoogle.com/projects/#6208860931489792
>

GSoC 2018: Congratulations to the selected student and mentors

[Umesh Singla]

Hello everyone,

Google just announced 1,264 projects for this year's summer of code. I'm
happy to share with you all that as requested MacPorts got one slot for the
following project:

1. Vishnu M
Project: Creating a dynamic website for Ports Index [1]
Mentors: Mojca Miklavec and Jackson Isaac

This goes without saying but I'm just reiterating:

1. I would like the student and the mentors to publicly interact with the
community on the mailing list (preferably under a single thread) and IRC so
that the rest of the community is able to follow the project and help you
in case mentors go temporarily offline.

2. I would like the student and mentors to come up with a communication
plan (how often do you want to meet, platform - mail/IRC/video) as soon as
possible. This is really necessary so everyone has a clear idea from the
beginning what to expect out of the project.

This time until only the mid of May is meant for community bonding period,
so learning any tools required or improving the project plan needs to be
taken up before the official coding period begins.

I hope others will add more to this email. I'll myself add more to this
once my exams get over.

Regards,
Umesh

[1]: https://summerofcode.withgoogle.com/projects/#6208860931489792

Re: MP manpages (was: Migrating the guide to AsciiDoc)

[Andrew Moore]

On Apr 23, 2018, at 3:46 PM, Jan Stary  wrote:
> 
> On Apr 23 16:26:13, rai...@macports.org wrote:
>> On 2018-04-23 14:27, Jan Stary wrote:
 These quirks are added by DocBook XSLT and are apparently required to
 make the output compatible. If you disagree with that, talk to DocBook
 why they added them.
>>> 
>>> You don't care that a 2008 workaround to a Debian bug
>>> is included in every manpage of a MacPorts package system?
>>> Or a 2009 workaround to a Solaris bug in GNU roff?
>>> Don't you find it a prime example of clutter
>>> that simply does not belong there?
>> 
>> No, I really do not care about these workarounds. Why should I care
>> about workarounds in intermediate formats?
>> I do not see anything of this in my terminal.
> 
> The asciidoc is what you don't see on you terminal.
> The resulting man(7) page is what you see, rendered
> by either groff (typically) or mandoc.
> 
>> Again, this is added to every man page produced by DocBook and not
>> specific to the man pages generated for MacPorts. We are not maintaining
>> the XSLT stylesheets that produce this output. If you think these
>> workarounds are not necessary, the DocBook project is the right address
>> for complaints.
> 
> I have no desire to "fix docbook", overengineered beyond absurdity.
> My point is why do you want to use something like docbook
> to produce the manpages?

Jan,
For what it’s worth, I like  mdoc(7)  and use it for my utilities - I even 
wrote one 
for the Apple's afconvert(1) utility (see attachment) - but for anything 
intended for
distribution,  the documentation gets rewritten in at least one other format, 
e.g., texinfo
and/or markdown.

There is no universal documentation format, e.g., ISO 8000 companies have their
own problem.

> All of OpenBSD, FreeBSD and NetBSD, in fact. And MacOS of course.
> (I love how you try to make it sound as something negligible.
> Remember how everyone except some BSD projects was using ssh.com
> before OpenSSH was started in some BSD project?)

Actually, if you download FreeBSD project documentation, e.g., 
https://github.com/freebsd/freebsd-doc,
you’ll find that it’s written in DocBook.

Again, for what it’s worth, while I’m not willing to maintain MacPorts mdoc(7) 
pages, I am
willing to explore improving conversion from asciidoc to mdoc, because for 
project-wide
documentation asciidoc seems like a reasonable choice.
-AM




afconvert.1
Description: Binary data

Re: GSOC

[Mojca Miklavec]

On 23 April 2018 at 19:23, Abhishek Kashyap wrote:
> Why my proposals was rejected.What is the reason behind it?
> I have tried my best.I have given my precious time to create my
> proposals.Reply soon as possible.

Dear Abhishek,

I hope we'll have an opportunity to send a longer response, but in
short: Google only granted us a single slot for GSOC this year.
Compared to the proposal that won that slot, we did not get any chance
to evaluate your skillset based on some sample code or some minimal
proof-of-concept code.


Some further general advice ...

One of the important suggestions for the future: there was
approximately a month of time to submit the proposals. The more time
student and mentors have to improve the proposal, the better the
proposal can get at the end. Submitting the proposal at the very end
of the allocated time window and expecting from mentors to provide an
instant response (within one hour?) is rarely going to work out well.

But we hope to have the ability to participate next year again. By far
the best way to increase your chances to get selected is by
contributing valuable patches to the project well  before the
application deadline. Students who can prove their ability to solve
problems related to the project have almost an "unfair advantage" over
those who just submit a prose. If you start contributing now at a slow
pace, to either this or some other project, you'll have the perfect
mileage by the time for GSOC 2019 to submit an outstanding proposal
backed by plenty patches and expertise.

Mojca

Re: MP manpages (was: Migrating the guide to AsciiDoc)

[Ryan Schmidt]

On Apr 23, 2018, at 14:46, Jan Stary wrote:

Man, you sure love to argue about stuff.


> The asciidoc is what you don't see on you terminal.
> The resulting man(7) page is what you see, rendered
> by either groff (typically) or mandoc.

Asciidoc is what we see in an editor when we edit the manual. The output of 
groff is what we see in the Terminal. All the intermediate stuff isn't 
particularly interesting to me as long as the input is easy enough to write and 
the output is legible.


>> Again, this is added to every man page produced by DocBook and not
>> specific to the man pages generated for MacPorts. We are not maintaining
>> the XSLT stylesheets that produce this output. If you think these
>> workarounds are not necessary, the DocBook project is the right address
>> for complaints.
> 
> I have no desire to "fix docbook", overengineered beyond absurdity.
> My point is why do you want to use something like docbook
> to produce the manpages?

As Rainer already explained:

> On Apr 23, 2018, at 06:17, Rainer Müller wrote:
> 
>> That is correct, DocBook XML is used because AsciiDoc has no native
>> backend to produce man pages.
>> 
>> However, AsciiDoctor has a native backend for man pages [1], which does
>> not require the additional step through DocBook XML. If you, or anyone
>> else, wants to look into switching the man page generation in base from
>> AsciiDoc to AsciiDoctor, that would be appreciated.


>>> How did you write the mdoc(7) manpages then?
>> 
>> Those had been written before I even joined the project. Apparently
>> someone wrote the original man pages, then left the project and no
>> longer contributed. Nobody updated the man pages because they were
>> written in a format nobody wanted to learn.
> 
> Are you sure _that_ was the reason? It's pretty damn trivial to
> update an _existing_ mdoc(7) manpage (such as: add an option, etc).

Ok, then what was the reason, since you don't believe us when we tell you what 
we think it was?


>> Therefore the plan came up
>> to replace that format with something else that is easier to pick up for
>> new contributors.
> 
> Honest question: how much did people start contributing documentation,
> after the switch from mdoc(7) to asciidoc?

I don't recall seeing a lot of substantial changes to the asciidoc after the 
conversion. But, the conversion included a complete modern rewrite of the 
manpages, such that additional contributions weren't immediately necessary. I 
think if we had not allowed the manpages to be converted to asciidoc, the 
person who did the rewrite would not have wanted to do so.


>> Although there was already some work to use DocBook XML for the man
>> pages, I proposed to use AsciiDoc in the NewHelpSystem. This format was
>> already used by other projects to write man pages. Just to name popular
>> examples, git and mercurial still use it. I do not think that the HTML
>> version of their man pages is missing semantics. I do not think that our
>> HTML version [1] is missing semantics, either.
> 
> What?
> 
> (> [1] https://man.macports.org/port-diagnose.1.html
> has almost no content; let's take port.1.html as an example:)
> 
> port
> [-bcdfknNopqRstuvy] [-D
> portdir] [-F cmdfile]
> [action] [actionflags]
> [[portname | pseudo-portname
> | port-expressions | port-url]]
>  [[@version] [+/-variant ] 
> [option=value ]]
> 
> There is _no_ semantics in here. Or what denotes an option here?
> Or its (optional) argument? Nothing. This is purely presentational:
> "put this in bold, type a bracket here".

Does that matter?


>> Back then, I did not even know there was a difference between man(7) and
>> mdoc(7). And even today, neither looks like a syntax new contributors
>> without previous knowledge want to write in my opinion.
> 
> I do. I am willing to write it.
> Please just say you simply don't want it.

I think that, having spent a very long time on rewriting the manpages in 
asciidoc--a process which is not yet 100% complete--we're now unclear on why we 
would want to convert to yet another different format now.

Re: Add a section on license names to the MacPorts guide?

[Ryan Schmidt]

On Apr 23, 2018, at 14:19, Perry E. Metzger wrote:

> I'm thinking of adding the following to the MacPorts guide because we
> often have problems with people picking invalid license names in
> Portfile submissions.
> 
> That said, I'm not sure this is the best text for it. Thoughts?

I don't want yet another copy of the list of valid licenses, to become out of 
sync with the others. We already have them on a wiki page. If you want to 
*move* the list from the wiki page to the guide (leaving the wiki page 
essentially blank except for a link to the corresponding place in the guide), 
that would be great.

There was also talk at one point about switching from our somewhat custom 
license names to an official standard, such as https://spdx.org/licenses/, at 
which point we wouldn't need to keep our own list, but we're not there yet. (Is 
anybody working on that?)

MP manpages (was: Migrating the guide to AsciiDoc)

[Jan Stary]

On Apr 23 16:26:13, rai...@macports.org wrote:
> On 2018-04-23 14:27, Jan Stary wrote:
> >> These quirks are added by DocBook XSLT and are apparently required to
> >> make the output compatible. If you disagree with that, talk to DocBook
> >> why they added them.
> > 
> > You don't care that a 2008 workaround to a Debian bug
> > is included in every manpage of a MacPorts package system?
> > Or a 2009 workaround to a Solaris bug in GNU roff?
> > Don't you find it a prime example of clutter
> > that simply does not belong there?
> 
> No, I really do not care about these workarounds. Why should I care
> about workarounds in intermediate formats?
> I do not see anything of this in my terminal.

The asciidoc is what you don't see on you terminal.
The resulting man(7) page is what you see, rendered
by either groff (typically) or mandoc.

> Again, this is added to every man page produced by DocBook and not
> specific to the man pages generated for MacPorts. We are not maintaining
> the XSLT stylesheets that produce this output. If you think these
> workarounds are not necessary, the DocBook project is the right address
> for complaints.

I have no desire to "fix docbook", overengineered beyond absurdity.
My point is why do you want to use something like docbook
to produce the manpages?

>  Then read the port-diagnose.1 below, written in mdoc(7).
>  Which one is cleaner, simpler, more readable, more writable, shorter?
> 
>  I offer to rewrite them.
> >>
> >> We moved away from mdoc(7) with the NewHelpSystem [1]. It took us about
> >> five years to write all man pages, including conversion of the old man
> >> pages.
> > 
> > $ cd /opt/mports/macports-base/doc
> > $ wc -l *.txt *.1 *.5 *.7
> > 
> > That would make it about nine lines per day.>
> > BTW, was it mdoc(7) or man(7)?
> 
> mdoc(7).
> 
> You seem to count both the input and the output files. Also, some of the
> old files, such as portfile.7 and porthier.7, still have not been
> converted. The real progress was even slower than that.
> 
> > How did you write the mdoc(7) manpages then?
> 
> Those had been written before I even joined the project. Apparently
> someone wrote the original man pages, then left the project and no
> longer contributed. Nobody updated the man pages because they were
> written in a format nobody wanted to learn.

Are you sure _that_ was the reason? It's pretty damn trivial to
update an _existing_ mdoc(7) manpage (such as: add an option, etc).

> Therefore the plan came up
> to replace that format with something else that is easier to pick up for
> new contributors.

Honest question: how much did people start contributing documentation,
after the switch from mdoc(7) to asciidoc?

> Although there was already some work to use DocBook XML for the man
> pages, I proposed to use AsciiDoc in the NewHelpSystem. This format was
> already used by other projects to write man pages. Just to name popular
> examples, git and mercurial still use it. I do not think that the HTML
> version of their man pages is missing semantics. I do not think that our
> HTML version [1] is missing semantics, either.

What?

(> [1] https://man.macports.org/port-diagnose.1.html
has almost no content; let's take port.1.html as an example:)

port
[-bcdfknNopqRstuvy] [-D
portdir] [-F cmdfile]
[action] [actionflags]
 [[portname | pseudo-portname
 | port-expressions | port-url]]
  [[@version] [+/-variant ] 
  [option=value ]]

There is _no_ semantics in here. Or what denotes an option here?
Or its (optional) argument? Nothing. This is purely presentational:
"put this in bold, type a bracket here".

> Back then, I did not even know there was a difference between man(7) and
> mdoc(7). And even today, neither looks like a syntax new contributors
> without previous knowledge want to write in my opinion.

I do. I am willing to write it.
Please just say you simply don't want it.

> I see you are strongly attached to mdoc(7), but take a look around:
> except some *BSD projects nobody uses mdoc(7) to write man pages.

All of OpenBSD, FreeBSD and NetBSD, in fact. And MacOS of course.
(I love how you try to make it sound as something negligible.
Remember how everyone except some BSD projects was using ssh.com
before OpenSSH was started in some BSD project?)

$ vi `man -w ls`

> Most
> projects use lightweight markup languages such as AsciiDoc, Markdown, or
> restructuredText, or even pod2man for this task.

No, most project don't. and even if they did,
is that a reason to do it too?

> $ find /opt/local/share/man | wc -l
>15591
> $ find /opt/local/share/man -exec zgrep -l '^.Dt' {} + | wc -l
>  588

Well, that differs by user of course:

$ find /opt/local/share/man -type f | wc -l
3493
$ find /opt/local/share/man -type f | xargs -n1 zgrep ^.TH | wc -l
2574
$ find /opt/local/share/man -type f | xargs -n1 zgrep ^.Dt | wc -l
 537

Also, this just greps for man(7) manpages;
that does not mean they are produced by asciidoc 

Add a section on license names to the MacPorts guide?

[Perry E. Metzger]

I'm thinking of adding the following to the MacPorts guide because we
often have problems with people picking invalid license names in
Portfile submissions.

That said, I'm not sure this is the best text for it. Thoughts?

Perry

diff --git a/guide/xml/portfile-keywords.xml b/guide/xml/portfile-keywords.xml
index 77559a4..066cc53 100644
--- a/guide/xml/portfile-keywords.xml
+++ b/guide/xml/portfile-keywords.xml
@@ -244,6 +244,16 @@
 sub-list.
 
 
+Valid licenses are one of the following: afl agpl apache
+apsl artistic autoconf beopen bitstreamvera boost bsd bsd-old
+cc-by cc-by-sa cddl cecill cecill-b cecill-c cnri copyleft cpl
+curl epl fpll fontconfig freetype gd gfdl gpl gplconflict
+ibmpl ijg isc jasper lgpl libtool lppl mit mpl ncsa
+noncommercial openldap openssl permissive php psf
+public-domain qpl restrictive/distributable ruby sleepycat
+ssleay tcl/tk vim w3c wtfpl wxwidgets x11 zlib zpl
+
+
 If the version number is a
 .0 version, the .0 should be
 omitted to make the version an integer. If the author gives the choice


-- 
Perry E. Metzgerpe...@piermont.com

Re: Migrating the guide to AsciiDoc

[Andrew Moore]

On Apr 23, 2018, at 11:42 AM, Rainer Müller  wrote:
> 
> On 2018-04-22 09:29, Mojca Miklavec wrote:
>> Hi,
>> 
>> As requested during yesterday's meeting, here's the result of
>> automatic conversion of our guide from xml (docbook) to asciidoc:
>> 
>>https://github.com/macports/macports-guide/tree/master/guide/adoc
>> 
>> This was initially explored by Aljaž and gives quite nice results
>> out-of-the-box, but there are still some issues with conversion that 
>> will have to be addressed either by fixing docbookrx itself or
>> manually.
> 
> Ruby and gems are really strange…

I had the impression that MacPorts rb-* gems were completely abandoned.  I 
haven't run ruby2.3 for a while, but have no  problem with either ruby2.5 or 
ruby2.6dev.

You might try:

$ sudo gem update —system

which should install the latest version of bundler (you really want that), and 
go from there.
In the particular case of nokogiri, you might also try running `gem install 
nokogiri` as user root.

$ ruby --version
ruby 2.6.0dev (2018-04-23) [x86_64-darwin17]
$ bundle --version
Bundler version 1.16.1
$ git clone https://github.com/asciidoctor/docbookrx
…
$ cd docbookrx
$ bundle
Fetching gem metadata from https://rubygems.org/..
Resolving dependencies...
Fetching rake 10.4.2
Installing rake 10.4.2
Using bundler 1.16.1
Using diff-lcs 1.3
Using mini_portile2 2.3.0
Using nokogiri 1.8.2
Using docbookrx 1.0.0.dev from source at `.`
Fetching rspec-support 3.4.1
Installing rspec-support 3.4.1
Fetching rspec-core 3.4.4
Installing rspec-core 3.4.4
Fetching rspec-expectations 3.4.0
Installing rspec-expectations 3.4.0
Fetching rspec-mocks 3.4.1
Installing rspec-mocks 3.4.1
Fetching rspec 3.4.0
Installing rspec 3.4.0
Bundle complete! 3 Gemfile dependencies, 11 gems now installed.
Use `bundle info [gemname]` to see where a bundled gem is installed.
$ rake build
docbookrx 1.0.0.dev built to pkg/docbookrx-1.0.0.dev.gem.
$ sudo gem install pkg/docbookrx-1.0.0.dev.gem 
Successfully installed docbookrx-1.0.0.dev
Parsing documentation for docbookrx-1.0.0.dev
Installing ri documentation for docbookrx-1.0.0.dev
Done installing documentation for docbookrx after 2 seconds
1 gem installed
$

Re: [macports-ports] 01/01: icu: update to 61.1

[Leonardo Brondani Schenkel]

On 2018-04-23 19:25, Joshua Root wrote:

On 2018-4-24 03:19 , Ken Cunningham wrote:

Revert? No many would have the accidental update

The commit was never on master, so there's no problem.


Yes, I usually work on a branch exactly to protect against pushing to 
the wrong repo by accident. That day came today. I deleted the branch 
moments after pushing.


I'm almost finished with the revbump of dependant ports, will create a 
PR within the hour.


// Leonardo.

Re: [macports-ports] 01/01: icu: update to 61.1

[Joshua Root]

On 2018-4-24 03:19 , Ken Cunningham wrote:
> 
> On 2018-04-23, at 9:46 AM, Leonardo Brondani Schenkel wrote:
> 
>> On 2018-04-23 18:07, Ryan Schmidt wrote:
>>> I've been meaning to revisit updating icu, now that we have the cxx11 1.1 
>>> portgroup. Let me know what you discover!
>>
>> I meant to push this to a branch on my fork, ended up pushing to MacPorts 
>> repo by mistake. Deleted the branch a few seconds after pushing once I 
>> realized by mistake and then pushed to my fork.
>>
>> I want to revbump all dependents and send a PR to you, but I cannot really 
>> test all affected ports. Any suggestions?
>>
>> // Leonardo.
>>
> 
> Revert? No many would have the accidental update
> 
> Ride it out? See how the dust settles, and get it all fixed up. Might as well 
> do this, I guess, unless icu is a bootstrap dep for something that leads to 
> cxx11 working.

The commit was never on master, so there's no problem.

- Josh

GSOC

[Abhishek Kashyap]

Why my proposals was rejected.What is the reason behind it?
I have tried my best.I have given my precious time to create my
proposals.Reply soon as possible.

Re: [macports-ports] 01/01: icu: update to 61.1

[Ken Cunningham]

On 2018-04-23, at 9:46 AM, Leonardo Brondani Schenkel wrote:

> On 2018-04-23 18:07, Ryan Schmidt wrote:
>> I've been meaning to revisit updating icu, now that we have the cxx11 1.1 
>> portgroup. Let me know what you discover!
> 
> I meant to push this to a branch on my fork, ended up pushing to MacPorts 
> repo by mistake. Deleted the branch a few seconds after pushing once I 
> realized by mistake and then pushed to my fork.
> 
> I want to revbump all dependents and send a PR to you, but I cannot really 
> test all affected ports. Any suggestions?
> 
> // Leonardo.
> 

Revert? No many would have the accidental update

Ride it out? See how the dust settles, and get it all fixed up. Might as well 
do this, I guess, unless icu is a bootstrap dep for something that leads to 
cxx11 working.

Ken

Re: [macports-ports] 01/01: icu: update to 61.1

[Leonardo Brondani Schenkel]

On 2018-04-23 18:07, Ryan Schmidt wrote:

I've been meaning to revisit updating icu, now that we have the cxx11 1.1 
portgroup. Let me know what you discover!


I meant to push this to a branch on my fork, ended up pushing to 
MacPorts repo by mistake. Deleted the branch a few seconds after pushing 
once I realized by mistake and then pushed to my fork.


I want to revbump all dependents and send a PR to you, but I cannot 
really test all affected ports. Any suggestions?


// Leonardo.

Re: [macports-ports] 01/01: icu: update to 61.1

[Ryan Schmidt]

On Apr 23, 2018, at 08:36, Leonardo Brondani Schenkel wrote:

> Leonardo Brondani Schenkel (lbschenkel) pushed a commit to branch icu
> in repository macports-ports.
> 
> 
> https://github.com/macports/macports-ports/commit/0c47ec4d30dc02c085dd851262cf2fcbbb0b1521
> 
> commit 0c47ec4d30dc02c085dd851262cf2fcbbb0b1521
> 
> Author: Leonardo Brondani Schenkel
> AuthorDate: Mon Apr 23 15:36:11 2018 +0200
> 
> icu: update to 61.1
> 
> ---
>  devel/icu/Portfile|  16 +--
>  devel/icu/files/CVE-2017-14952.patch  |  12 --
>  devel/icu/files/CVE-2017-7867-CVE-2017-7868.patch | 156 
> --
>  3 files changed, 8 insertions(+), 176 deletions(-)
> 
> 
> diff --git a/devel/icu/Portfile b/devel/icu/Portfile
> index 308b564..a44341b 100644
> --- a/devel/icu/Portfile
> +++ b/devel/icu/Portfile
> @@ -8,7 +8,7 @@ set my_name icu4c
>  # whenever the library version number changes. Thanks.
>  # To find dependencies, use:
>  # port file all | sort -u | xargs grep -El ':icu( |$)' | rev | cut -d / -f 2 
> | rev | sort -u
> -version 58.2
> +version 61.1
>  # Don't update to 59 or later because they require C++11
>  categories  devel textproc
>  platforms   darwin freebsd

I've been meaning to revisit updating icu, now that we have the cxx11 1.1 
portgroup. Let me know what you discover!

Re: Migrating the guide to AsciiDoc

[Rainer Müller]

On 2018-04-22 09:29, Mojca Miklavec wrote:
> Hi,
> 
> As requested during yesterday's meeting, here's the result of
> automatic conversion of our guide from xml (docbook) to asciidoc:
> 
> https://github.com/macports/macports-guide/tree/master/guide/adoc
> 
> This was initially explored by Aljaž and gives quite nice results
> out-of-the-box, but there are still some issues with conversion that
> will have to be addressed either by fixing docbookrx itself or
> manually.

Ruby and gems are really strange...

Apparently, installing nokogiri with bundle fails because it tries to
execute pkg-config with DYLD_LIBRARY_PATH set, for whatever reason. This
leads to crashes as it draws in incompatible versions of libjpeg. I was
not even able to determine where this DYLD_LIBRARY_PATH in the
environment is coming from.

Here is a way to get it working:

$ git clone https://github.com/asciidoctor/docbookrx
$ cd docbookrx
$ sudo port install rb23-bundler
$ bundle-2.3 config --local build.nokogiri --use-system-libraries 
--with-xml2-dir=/opt/local --with-xml2-include=/opt/local/include/libxml2 
--with-xslt-dir=/opt/local --with-zlib-dir=/opt/local 
--with-exslt-dir=/opt/local --without-pkg-config
$ bundle-2.3 install --path=.bundle/gems

Then go to the guide/xml/ directory of macports-guide:

$ BUNDLE_GEMFILE=~/src/docbookrx/Gemfile bundle-2.3 exec docbookrx guide.xml
$ mv *.adoc ../adoc/

Rainer

Re: Migrating the guide to AsciiDoc

[Rainer Müller]

On 2018-04-23 14:27, Jan Stary wrote:
>> These quirks are added by DocBook XSLT and are apparently required to
>> make the output compatible. If you disagree with that, talk to DocBook
>> why they added them.
> 
> You don't care that a 2008 workaround to a Debian bug
> is included in every manpage of a MacPorts package system?
> Or a 2009 workaround to a Solaris bug in GNU roff?
> Don't you find it a prime example of clutter
> that simply does not belong there?

No, I really do not care about these workarounds. Why should I care
about workarounds in intermediate formats? I do not see anything of this
in my terminal.

Again, this is added to every man page produced by DocBook and not
specific to the man pages generated for MacPorts. We are not maintaining
the XSLT stylesheets that produce this output. If you think these
workarounds are not necessary, the DocBook project is the right address
for complaints.

 Then read the port-diagnose.1 below, written in mdoc(7).
 Which one is cleaner, simpler, more readable, more writable, shorter?

 I offer to rewrite them.
>>
>> We moved away from mdoc(7) with the NewHelpSystem [1]. It took us about
>> five years to write all man pages, including conversion of the old man
>> pages.
> 
> $ cd /opt/mports/macports-base/doc
> $ wc -l *.txt *.1 *.5 *.7
> 
> That would make it about nine lines per day.>
> BTW, was it mdoc(7) or man(7)?

mdoc(7).

You seem to count both the input and the output files. Also, some of the
old files, such as portfile.7 and porthier.7, still have not been
converted. The real progress was even slower than that.

> How did you write the mdoc(7) manpages then?

Those had been written before I even joined the project. Apparently
someone wrote the original man pages, then left the project and no
longer contributed. Nobody updated the man pages because they were
written in a format nobody wanted to learn. Therefore the plan came up
to replace that format with something else that is easier to pick up for
new contributors.

Although there was already some work to use DocBook XML for the man
pages, I proposed to use AsciiDoc in the NewHelpSystem. This format was
already used by other projects to write man pages. Just to name popular
examples, git and mercurial still use it. I do not think that the HTML
version of their man pages is missing semantics. I do not think that our
HTML version [1] is missing semantics, either.

Back then, I did not even know there was a difference between man(7) and
mdoc(7). And even today, neither looks like a syntax new contributors
without previous knowledge want to write in my opinion.

I see you are strongly attached to mdoc(7), but take a look around:
except some *BSD projects nobody uses mdoc(7) to write man pages. Most
projects use lightweight markup languages such as AsciiDoc, Markdown, or
restructuredText, or even pod2man for this task.

$ find /opt/local/share/man | wc -l
   15591
$ find /opt/local/share/man -exec zgrep -l '^.Dt' {} + | wc -l
 588

Rainer

[1] https://man.macports.org/port-diagnose.1.html

Re: Migrating the guide to AsciiDoc

[Jan Stary]

On Apr 23 13:17:10, rai...@macports.org wrote:
> On 2018-04-23 10:12, Jan Stary wrote:
> >>> We are already using the AsciiDoc format for our man pages,
> >>
> >> Manpages are supposed to be written in mdoc(7), the language of
> >> manpages, just like e.g. /usr/share/man/man1/ls.1 is.
> >>
> >> The current port-* manpages are horrible
> >> (not talking about content, but markup).
> >>
> >> Look at e.g. port-diagnose.1; read it, line by line.
> >> Note the 2008 workarounds to debian bugs.
> >> Note the 2009 workarouns to GNU roff.
> >> Note the pointless low-level roff(7) tweaks.
> > 
> > 
> > https://lists.gnu.org/archive/html/groff/2014-02/msg00109.html
> 
> I do not care about the raw input,

(apparently)

> I read man pages in rendered form with man(1).

I thought we are talking about _producing_ the manpages.
That _is_ the raw input (in whichever markup language).

> These quirks are added by DocBook XSLT and are apparently required to
> make the output compatible. If you disagree with that, talk to DocBook
> why they added them.

You don't care that a 2008 workaround to a Debian bug
is included in every manpage of a MacPorts package system?
Or a 2009 workaround to a Solaris bug in GNU roff?
Don't you find it a prime example of clutter
that simply does not belong there?

> >> Then read the port-diagnose.1 below, written in mdoc(7).
> >> Which one is cleaner, simpler, more readable, more writable, shorter?
> >>
> >> I offer to rewrite them.
> 
> We moved away from mdoc(7) with the NewHelpSystem [1]. It took us about
> five years to write all man pages, including conversion of the old man
> pages.

$ cd /opt/mports/macports-base/doc
$ wc -l *.txt *.1 *.5 *.7

That would make it about nine lines per day.

BTW, was it mdoc(7) or man(7)?

> >> .Dd April 23, 2018
> >> .Dt PORT-DIAGNOSE 1
> >> .Os
> >> .Sh NAME
> >> .Nm port diagnose
> >> .Nd detects common issues with macports
> >> .Sh SYNOPSIS
> >> .Nm port
> >> .Ic diagnose
> >> .Op Fl -quiet
> >> .Sh DESCRIPTION
> >> .Nm port
> >> .Ic diagnose
> >> will check a list of common issues that could
> >> affect the user of MacPorts in one way or another.
> >> If any issues are found, a warning will be
> >> shown to the user included with a possible fix.
> >> .Pp
> >> With the
> >> .Fl -quiet
> >> option, only warnings and errors are displayed.
> >> .Sh SEE ALSO
> >> .Xr port 1
> >> .Sh AUTHORS
> >> .An Kyle Sammons Aq Mt ksamm...@macports.org
> 
> I really cannot see the benefits of this. To me, writing this by hand
> would be even more terrible than writing XML.

> I have no idea what any of
> these two-character commands mean.

How did you write the mdoc(7) manpages then?

> This syntax is far from being intuitive.

Nm  name
Op Fl   optional flag
Ar  argument
Sh  section header

Seriously, it takes about 15 minutes to get going.
http://mandoc.bsd.lv/man/mdoc.7.html


The main point is that mdoc(7) allows for constructs like

.Op Fl f Ar arg

meaning

there is an optional 'f' flag
which takes an 'arg' argument

as opposed to

switch to italics, type a bracket, a dash, "f",
then switch to boldface and type "arg"

in the physical roff markup of man(7).
Similarly for other constructs like cross-references,
filenames, author emails, env variables, etc.

> Yes, it seems to be possible to encode more semantics than with
> AsciiDoc. But do we really need that in a man page?

Yes; you can _search_ by those semantics then, such as by
a filename mentioned in FILES; or by AUTHORS; you get html manpages
for free and can do things like http://man.openbsd.org/ls#d
i.e. link to individual options and sections.

> But do we really need that in a man page?

Do we need 2008 workarounds to Debian bugs in a manpage?

> At least for terminal output, almost everything of that
> is lost with rendering anyway.

No it's not. And terminal output is not the only:
you get html, pdf, ps, even mandoc from it, without docbook;
mdoc(7) is a language that has been in UNIX for decades
and is very well supported everywhere.

> If you really care that much about the non-rendered file on disk,
> I would recommend to rewrite the DocBook XSLT to use the mdoc(7) format
> or contribute a native backend for it to AsciiDoctor.

I'm not touching DocBook, obviously.
My main motivation here is to get rid of it entirely.
And asciidoc has no way of even expressing the semantics.

Again, I am willing to do the work.
Please let me know if there is no interest.

Jan

Re: Migrating the guide to AsciiDoc

[Rainer Müller]

On 2018-04-23 10:42, Jan Stary wrote:
> Also, having manpages written in asciidoc means we need
> the abominable docbook to actually produce the man(7) pages, right?
> At least that's what it says at the end of install:
> 
>   * Warning: Using pre-generated man pages only.
>   * asciidoc, xsltproc (port libxslt) and docbook-xsl are required
> to generate man pages from source.

That is correct, DocBook XML is used because AsciiDoc has no native
backend to produce man pages.

However, AsciiDoctor has a native backend for man pages [1], which does
not require the additional step through DocBook XML. If you, or anyone
else, wants to look into switching the man page generation in base from
AsciiDoc to AsciiDoctor, that would be appreciated.

Rainer

[1]
https://github.com/asciidoctor/asciidoctor/blob/master/lib/asciidoctor/converter/manpage.rb

Re: Migrating the guide to AsciiDoc

[Rainer Müller]

On 2018-04-23 10:12, Jan Stary wrote:
>>> We are already using the AsciiDoc format for our man pages,
>>
>> Manpages are supposed to be written in mdoc(7), the language of
>> manpages, just like e.g. /usr/share/man/man1/ls.1 is.
>>
>> The current port-* manpages are horrible
>> (not talking about content, but markup).
>>
>> Look at e.g. port-diagnose.1; read it, line by line.
>> Note the 2008 workarounds to debian bugs.
>> Note the 2009 workarouns to GNU roff.
>> Note the pointless low-level roff(7) tweaks.
> 
> 
> https://lists.gnu.org/archive/html/groff/2014-02/msg00109.html

I do not care about the raw input, I read man pages in rendered form
with man(1).

These quirks are added by DocBook XSLT and are apparently required to
make the output compatible. If you disagree with that, talk to DocBook
why they added them.

>> Then read the port-diagnose.1 below, written in mdoc(7).
>> Which one is cleaner, simpler, more readable, more writable, shorter?
>>
>> I offer to rewrite them.

We moved away from mdoc(7) with the NewHelpSystem [1]. It took us about
five years to write all man pages, including conversion of the old man
pages.

>> .Dd April 23, 2018
>> .Dt PORT-DIAGNOSE 1
>> .Os
>> .Sh NAME
>> .Nm port diagnose
>> .Nd detects common issues with macports
>> .Sh SYNOPSIS
>> .Nm port
>> .Ic diagnose
>> .Op Fl -quiet
>> .Sh DESCRIPTION
>> .Nm port
>> .Ic diagnose
>> will check a list of common issues that could
>> affect the user of MacPorts in one way or another.
>> If any issues are found, a warning will be
>> shown to the user included with a possible fix.
>> .Pp
>> With the
>> .Fl -quiet
>> option, only warnings and errors are displayed.
>> .Sh SEE ALSO
>> .Xr port 1
>> .Sh AUTHORS
>> .An Kyle Sammons Aq Mt ksamm...@macports.org

I really cannot see the benefits of this. To me, writing this by hand
would be even more terrible than writing XML. I have no idea what any of
these two-character commands mean. This syntax is far from being intuitive.

Yes, it seems to be possible to encode more semantics than with
AsciiDoc. But do we really need that in a man page? At least for
terminal output, almost everything of that is lost with rendering anyway.

If you really care that much about the non-rendered file on disk,
I would recommend to rewrite the DocBook XSLT to use the mdoc(7) format
or contribute a native backend for it to AsciiDoctor.

Rainer

[1] https://trac.macports.org/wiki/NewHelpSystem

Re: updating pymol to 2.1.0 and PyQt interface

[g5pw]

> On 22 Apr 2018, at 16:34, Jack Howarth  > wrote:
> 
> Okay. I believe I have addressed all the concerns cited on
> 
> https://trac.macports.org/ticket/56139 
> 
> 
> Can someone commit the latest files for me?

Hello Jack!
I added a last comment, after that is resolved I can commit your port. Thank 
you for your contribution to Macports!

g5pw

--
Aljaž Srebrnič a.k.a g5pw
My public key:  https://g5pw.me/key 
Key fingerprint = 2109 8131 60CA 01AF 75EC  01BF E140 E1EE A54E E677

Re: Migrating the guide to AsciiDoc

[Jan Stary]

On Apr 23 10:09:06, mo...@macports.org wrote:
> On 23 April 2018 at 09:42, Jan Stary  wrote:
> > On Apr 22 09:29:53, mo...@macports.org wrote:
> >> As requested during yesterday's meeting, here's the result of
> >> automatic conversion of our guide from xml (docbook) to asciidoc:
> >>
> >> https://github.com/macports/macports-guide/tree/master/guide/adoc
> >>
> >> This was initially explored by Aljaž and gives quite nice results
> >> out-of-the-box,
> >
> > Thank you. Any format is better than xml,
> > and any tool is better than docbook.
> >
> >> but there are still some issues with conversion that
> >> will have to be addressed either by fixing docbookrx itself or
> >> manually.
> >>
> >> If anyone is willing to help in the process, your help will be appreciated.
> >
> > Is asciidoc what the user is upposed to read directly, as in e.g.
> > https://github.com/macports/macports-guide/blob/master/guide/adoc/installing.adoc
> 
> No.
> 
> > or is that considered an "internal" format to be ultimately converted
> > to html and put on a web page such as https://guide.macports.org/
> > where the user will read it?
> 
> Yes. The guide should be converted to HTML (and ideally also PDF).

Can the conversion to PDF happen without docbook?
(i.e. can asciidoc(tor|*) produce pdf itself?)

> The fact that GitHub can interpret the format is just a bonus that
> might also help developers when editing the page, but it's not meant
> to be the final product.

> > The Plan section says
> >
> >  First convert .adoc files back to docbook .xml format
> >  and use the existing toolchain to generate the html pages
> >  (to avoid further delays).
> >
> > That makes no sense to me: why convert back?
> > Cannot html pages be generated from adoc directly?
> > (And if so, why not use the original xml?)
> 
> Yes, one can directly generate html. But we need to figure out how to
> do page splitting etc. This is why Rainer suggested to temporarily go
> through docbook again. This is not absolutely set in stone though, if
> someone polishes the process to sufficient details to allow
> straightforwand conversion, we can use that one.
> 
> (I believe the main reason why going through docbook was considered
> was because none of us took the time to figure out how to make a
> multi-page html from asciidoc directly.)

Apparently, it still cannot do multi-page output:
https://github.com/asciidoctor/asciidoctor/issues/626
https://github.com/openSUSE/asciidoctor/issues/9

Which means this does not get rid of docbook:
it adds to the top of it (or the bottom of it).

Jan

Re: Migrating the guide to AsciiDoc

[Jan Stary]

On Apr 23 10:12:06, h...@stare.cz wrote:
> > > We are already using the AsciiDoc format for our man pages,
> > 
> > Manpages are supposed to be written in mdoc(7), the language of
> > manpages, just like e.g. /usr/share/man/man1/ls.1 is.
> > 
> > The current port-* manpages are horrible
> > (not talking about content, but markup).
> > 
> > Look at e.g. port-diagnose.1; read it, line by line.
> > Note the 2008 workarounds to debian bugs.
> > Note the 2009 workarouns to GNU roff.
> > Note the pointless low-level roff(7) tweaks.
> 
> https://lists.gnu.org/archive/html/groff/2014-02/msg00109.html
> 

Also, having manpages written in asciidoc means we need
the abominable docbook to actually produce the man(7) pages, right?
At least that's what it says at the end of install:

* Warning: Using pre-generated man pages only.
* asciidoc, xsltproc (port libxslt) and docbook-xsl are required
  to generate man pages from source.

Jan


> > Then read the port-diagnose.1 below, written in mdoc(7).
> > Which one is cleaner, simpler, more readable, more writable, shorter?
> > 
> > I offer to rewrite them.
> > 
> > Jan
> > 
> > 
> > .Dd April 23, 2018
> > .Dt PORT-DIAGNOSE 1
> > .Os
> > .Sh NAME
> > .Nm port diagnose
> > .Nd detects common issues with macports
> > .Sh SYNOPSIS
> > .Nm port
> > .Ic diagnose
> > .Op Fl -quiet
> > .Sh DESCRIPTION
> > .Nm port
> > .Ic diagnose
> > will check a list of common issues that could
> > affect the user of MacPorts in one way or another.
> > If any issues are found, a warning will be
> > shown to the user included with a possible fix.
> > .Pp
> > With the
> > .Fl -quiet
> > option, only warnings and errors are displayed.
> > .Sh SEE ALSO
> > .Xr port 1
> > .Sh AUTHORS
> > .An Kyle Sammons Aq Mt ksamm...@macports.org

Re: Migrating the guide to AsciiDoc

[Jan Stary]

> > We are already using the AsciiDoc format for our man pages,
> 
> Manpages are supposed to be written in mdoc(7), the language of
> manpages, just like e.g. /usr/share/man/man1/ls.1 is.
> 
> The current port-* manpages are horrible
> (not talking about content, but markup).
> 
> Look at e.g. port-diagnose.1; read it, line by line.
> Note the 2008 workarounds to debian bugs.
> Note the 2009 workarouns to GNU roff.
> Note the pointless low-level roff(7) tweaks.


https://lists.gnu.org/archive/html/groff/2014-02/msg00109.html


> Then read the port-diagnose.1 below, written in mdoc(7).
> Which one is cleaner, simpler, more readable, more writable, shorter?
> 
> I offer to rewrite them.
> 
>   Jan
> 
> 
> .Dd April 23, 2018
> .Dt PORT-DIAGNOSE 1
> .Os
> .Sh NAME
> .Nm port diagnose
> .Nd detects common issues with macports
> .Sh SYNOPSIS
> .Nm port
> .Ic diagnose
> .Op Fl -quiet
> .Sh DESCRIPTION
> .Nm port
> .Ic diagnose
> will check a list of common issues that could
> affect the user of MacPorts in one way or another.
> If any issues are found, a warning will be
> shown to the user included with a possible fix.
> .Pp
> With the
> .Fl -quiet
> option, only warnings and errors are displayed.
> .Sh SEE ALSO
> .Xr port 1
> .Sh AUTHORS
> .An Kyle Sammons Aq Mt ksamm...@macports.org

Re: Migrating the guide to AsciiDoc

[Mojca Miklavec]

On 23 April 2018 at 09:42, Jan Stary  wrote:
> On Apr 22 09:29:53, mo...@macports.org wrote:
>> As requested during yesterday's meeting, here's the result of
>> automatic conversion of our guide from xml (docbook) to asciidoc:
>>
>> https://github.com/macports/macports-guide/tree/master/guide/adoc
>>
>> This was initially explored by Aljaž and gives quite nice results
>> out-of-the-box,
>
> Thank you. Any format is better than xml,
> and any tool is better than docbook.
>
>> but there are still some issues with conversion that
>> will have to be addressed either by fixing docbookrx itself or
>> manually.
>>
>> If anyone is willing to help in the process, your help will be appreciated.
>
> Is asciidoc what the user is upposed to read directly, as in e.g.
> https://github.com/macports/macports-guide/blob/master/guide/adoc/installing.adoc

No.

> or is that considered an "internal" format to be ultimately converted
> to html and put on a web page such as https://guide.macports.org/
> where the user will read it?

Yes. The guide should be converted to HTML (and ideally also PDF).

The fact that GitHub can interpret the format is just a bonus that
might also help developers when editing the page, but it's not meant
to be the final product.

> On Apr 22 11:39:23, rai...@macports.org wrote:
>> AsciiDoc is both the name of the format and also the name of the
>> original reference implementation in Python, but development on that
>> ceased a few years ago. AsciiDoctor is an alternative implementation in
>> Ruby and actively being developed.
>
> Which one produced the current adoc from of the xml guide?

Neither of them, the conversion was done with docbookrx, the link is also on
https://github.com/macports/macports-guide/blob/master/guide/adoc/README.md
so
https://github.com/asciidoctor/docbookrx

> The Plan section says
>
>  First convert .adoc files back to docbook .xml format
>  and use the existing toolchain to generate the html pages
>  (to avoid further delays).
>
> That makes no sense to me: why convert back?
> Cannot html pages be generated from adoc directly?
> (And if so, why not use the original xml?)

Yes, one can directly generate html. But we need to figure out how to
do page splitting etc. This is why Rainer suggested to temporarily go
through docbook again. This is not absolutely set in stone though, if
someone polishes the process to sufficient details to allow
straightforwand conversion, we can use that one.

(I believe the main reason why going through docbook was considered
was because none of us took the time to figure out how to make a
multi-page html from asciidoc directly.)

Mojca

Re: Migrating the guide to AsciiDoc

[Jan Stary]

On Apr 22 09:29:53, mo...@macports.org wrote:
> As requested during yesterday's meeting, here's the result of
> automatic conversion of our guide from xml (docbook) to asciidoc:
> 
> https://github.com/macports/macports-guide/tree/master/guide/adoc
> 
> This was initially explored by Aljaž and gives quite nice results
> out-of-the-box,

Thank you. Any format is better than xml,
and any tool is better than docbook.

> but there are still some issues with conversion that
> will have to be addressed either by fixing docbookrx itself or
> manually.
> 
> If anyone is willing to help in the process, your help will be appreciated.

Is asciidoc what the user is upposed to read directly, as in e.g.
https://github.com/macports/macports-guide/blob/master/guide/adoc/installing.adoc
or is that considered an "internal" format to be ultimately converted
to html and put on a web page such as https://guide.macports.org/
where the user will read it?

On Apr 22 11:39:23, rai...@macports.org wrote:
> AsciiDoc is both the name of the format and also the name of the
> original reference implementation in Python, but development on that
> ceased a few years ago. AsciiDoctor is an alternative implementation in
> Ruby and actively being developed.

Which one produced the current adoc from of the xml guide?


The Plan section says

 First convert .adoc files back to docbook .xml format
 and use the existing toolchain to generate the html pages
 (to avoid further delays).

That makes no sense to me: why convert back?
Cannot html pages be generated from adoc directly?
(And if so, why not use the original xml?)

> We are already using the AsciiDoc format for our man pages,

Manpages are supposed to be written in mdoc(7), the language of
manpages, just like e.g. /usr/share/man/man1/ls.1 is.

The current port-* manpages are horrible
(not talking about content, but markup).

Look at e.g. port-diagnose.1; read it, line by line.
Note the 2008 workarounds to debian bugs.
Note the 2009 workarouns to GNU roff.
Note the pointless low-level roff(7) tweaks.

Then read the port-diagnose.1 below, written in mdoc(7).
Which one is cleaner, simpler, more readable, more writable, shorter?

I offer to rewrite them.

Jan


.Dd April 23, 2018
.Dt PORT-DIAGNOSE 1
.Os
.Sh NAME
.Nm port diagnose
.Nd detects common issues with macports
.Sh SYNOPSIS
.Nm port
.Ic diagnose
.Op Fl -quiet
.Sh DESCRIPTION
.Nm port
.Ic diagnose
will check a list of common issues that could
affect the user of MacPorts in one way or another.
If any issues are found, a warning will be
shown to the user included with a possible fix.
.Pp
With the
.Fl -quiet
option, only warnings and errors are displayed.
.Sh SEE ALSO
.Xr port 1
.Sh AUTHORS
.An Kyle Sammons Aq Mt ksamm...@macports.org