search

Perl-Toolchain-Gang / ExtUtils-MakeMaker

Perl module to make Makefiles and build modules (what backs Makefile.PL)
https://metacpan.org/release/ExtUtils-MakeMaker
64 stars 76 forks source link

HTMLDIRs related RTs #111

Open mohawk2 opened 9 years ago

mohawk2 commented 9 years ago

https://rt.cpan.org/Ticket/Display.html?id=45732 https://rt.cpan.org/Ticket/Display.html?id=75705 https://rt.cpan.org/Ticket/Display.html?id=45600

mohawk2 commented 9 years ago

https://rt.cpan.org/Ticket/Display.html?id=37806

Leont commented 9 years ago

html support in the toolchain is currently a joke (Module::Build) to no-longer-existent (MakeMaker).

I'd be in favor of this changing, but I'm not particularly interested in the jak-shaving that would be involved in fixing this.

mohawk2 commented 9 years ago

I propose that EUMM should either support HTML generation properly, or not at all. I am told @ActiveState have a stake in this. What do people think?

mohawk2 commented 9 years ago

@jandubois, got any opinion?

jandubois commented 9 years ago

Schwern ripped out the HTML support added by ActiveState because it did work correctly in some cases (ActivePerl enforces a simplified install directory layout), so not sure what else you would expect...

I think this will be a hard problem to solve if you need to support the full combinatorial insanity of configurable and sharable installation paths supported by ./Configure. I wrote before about the concept of "install areas" that would help here, but I can't find it right now.

Personally I also think the time for locally installed HTML help has come and gone, and not many people use it anymore, but that would be anecdotal evidence at best.

mohawk2 commented 9 years ago

So if it were removed, would that cause any problems?

karenetheridge commented 9 years ago

Where can I read the documention on the feature(s) in question? Is it just the HTMLDIR argument for WriteMakefile()? I see no mention of such an argument...

mohawk2 commented 9 years ago

I think it is. In that case, it seems like it's Ok for me to just close the RT tickets on HTML*DIR, since they're moot?

karenetheridge commented 9 years ago

I think it is.

I'm not sure what you're replying to.

it seems like it's Ok for me to just close the RT tickets on HTML*DIR

Whoa there. I'm still trying to understand what feature(s) are being talked about here.

mohawk2 commented 9 years ago

I replied "I think it is" to the only question you asked starting with "Is it...".

karenetheridge commented 9 years ago

But I see no mention of any HTMLDIR argument in the documentation. <-- my actual point

dolmen commented 9 years ago

Pod::POM::Web (and my ::PSGI wrapper) is a very good solution for those who want local HTML. It even offers indexed search.

HTML generation by install tools is just a waste of resources: machine (disk space, CPU at generation time) and human (maintenance).

mohawk2 commented 9 years ago

@karenetheridge it seems there used to be such a feature then @schwern deleted it. Is there any reason for the RT tickets to remain open?

schwern commented 9 years ago

I didn't do a good job documenting why it was removed. It did not honor PREFIX nor INSTALL_BASE which was considered an unacceptable bug to be left in the wild. In dc5c2721c8ee27eac6aa8aad32e30ac107c085bf HTML doc generation was removed and put into its own branch for repair. That branch now seems to be gone.

Rather than trying to implement HTML generation again, I would recommend writing an API for doc generation plugins. Why?

The plugin method would likely need to be handed...

As to the existing RT tickets, examine them for situations the new system must deal with, turn them into Github issues, and then close them.

Leont commented 9 years ago

I think externalizing the HTML generation is a good idea. I'm not expecting any other formats to pop up and become relevant in the near or medium future.

We already have the basic infrastructure for installing HTML in core/%Config, and INSTALLBLAHTYPE variables are cheap. I do think MakeMaker should remain responsible for installing said documents (in fact, if only because otherwise packlists and other things would suddenly stop working).

dolmen commented 9 years ago

Leon wrote:

I think externalizing the HTML generation is a good idea. I'm not expecting any other formats to pop up and become relevant in the near or medium future.

The other format currently supported by EUMM is "man" and it is only relevant on Unix(-like) platforms.

somian commented 9 years ago

​Jan makes a valid point [1]​

On Mon, Dec 8, 2014 at 7:03 PM, Jan Dubois wrote:

I think this will be a hard problem to solve if you need to support the full combinatorial insanity of configurable and sharable installation paths supported by ./Configure. I wrote before about the concept of "install areas" that would help here, but I can't find it right now.

​[1] ​ Personally I also think the time for locally installed HTML help has come and gone, and not many people use it anymore, but that would be anecdotal evidence at best.

Yet. Surely there will be some cases in which the software supplier is contractually required to provide locally-accessible documentation in some form, and the spec being worked with might require it to be HTML. This possiblity alone suggests that individually, coders &|| coders+their teams will still be working on making Perl CPAN distros automatically generate HTML documentation.

​The (textually previous) point made:

​I think this will be a hard problem to solve if you need to support the full combinatorial insanity of configurable and sharable installation paths supported by ./Configure.

​is also accurate and in the vernacular, Oi! Oi!. It is a real tough one. Any solution might end up involving some compromises that will leave some parties with cause to complain. But that's par for the course for​ build automata, isn't it? Most people being mostly happy with a direction that's been taken: that is a great success.

​Soren 'tino / somian / Intrepid Buffalo, NY ​"The Virtue of Liberality": The cultivated disposition to recognize and appreciate truths and values other than one's own.

dolmen commented 9 years ago

@somian Could you reformat your post on Github? Your own point is hard to get due to formatting.

somian commented 9 years ago

​I contribute very seldom to this discussion.​ What did I do?

On Fri, Dec 12, 2014 at 5:47 AM, Olivier Mengué notifications@github.com wrote:

Could you reformat your post on Github? Your own point is hard to get due to formatting.

​I will do so. To prevent the problem in the future let's figure this out; all that I did was compose the reply in Gmail. Is it possible that I forgot to turn off rich formatting? OH, yakshavings. Yeah, I did. Sorry!​

"I have decades of experience with troubleshooting MS Windows problems, often successfully. That doesn't mean I enjoy it. It's like becoming an adept at presiding over funerals."

mohawk2 commented 9 years ago

I have re-reviewed the four RT tickets with a view to @schwern's points above. They all covered essentially the the same point, that HTML install locations must respect the INSTALL_BASE/PREFIX vars. Therefore I put essentially this comment on them (with one variation) and marked them as resolved:

HTML generation support was removed some time ago. Further to the discussion in https://github.com/Perl-Toolchain-Gang/ExtUtils-MakeMaker/issues/111, I am extracting the points from the four HTML*DIR RT tickets onto the GH issue, then closing the tickets.

The points disclosed in this ticket (must respect INSTALL* and PREFIX) are already covered by schwern's comment on a design for a doc plugin system.

I am marking this ticket as resolved.