www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Any ddox experts n da house?

reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
Hello,


I'm chatting with Vladimir on IRC and we reached the conclusion that 
neither of us has the expertise to maintain the ddox-based build, nor 
the bandwidth to get into it.

Is there someone who can help us with improving our ddox-based Phobos 
documentation build? There are several issues with it of varying 
gravity, nothing fundamental but a good chunk of work.

Counting on your help!


Thanks,

Andrei
Feb 14 2015
parent reply "Vladimir Panteleev" <vladimir thecybershadow.net> writes:
On Saturday, 14 February 2015 at 09:17:57 UTC, Andrei 
Alexandrescu wrote:

 Counting on your help!


Here are some things that would help:

1. Most urgently, update the .dt template to match the current 
Dlang.org style.

2. Ideally, the .dt templates need to be removed, and DDox made 
to use the existing DDoc templates. This is so future website 
updates are immediately reflected in DDox, to avoid this 
situation in the future.

3. Currently, DDox creates all .html files regardless if they've 
actually changed or not, thus making each generated file always 
have a new modification time. Because the website is uploaded via 
rsync, this greatly increases upload time. This can be solved by 
making DDox first create a Makefile include, or by simply making 
it not overwrite files with identical content.

There is generally something very broken about the DDox 
templates. I've attempted to fix the website by adding a copy of 
the old style.css, and I've modified layout.dt like so:

diff --git a/dpl-docs/views/layout.dt b/dpl-docs/views/layout.dt
index c4ddcb0..2960625 100644
--- a/dpl-docs/views/layout.dt
+++ b/dpl-docs/views/layout.dt
   -19,7 +19,7    html(lang='en-US')



-    link(rel='stylesheet', type='text/css', 

+    link(rel='stylesheet', type='text/css', 


type='text/javascript')

      script(type="text/javascript", 


Yet, no matter what I do, which files I delete or how I attempt 
to rebuild, the generated .html files still reference "style.css" 
and not "style-2014.css".

I'm also getting strange linker errors when attempting to rebuild 
DDox:

http://dump.thecybershadow.net/e6c93daabcbe9b01be9414d8d63913d8/0000009F.txt

These only happen SOMETIMES. They don't happen on a clean build. 
I haven't identified the pattern, but it seems to vary between 
working and not working without me changing anything in the 
environment.
Feb 14 2015
next sibling parent reply Mathias Lang via Digitalmars-d <digitalmars-d puremagic.com> writes:
2015-02-14 10:46 GMT+01:00 Vladimir Panteleev via Digitalmars-d <
digitalmars-d puremagic.com>:


 On Saturday, 14 February 2015 at 09:17:57 UTC, Andrei Alexandrescu wrote:


 Counting on your help!


 Here are some things that would help:

 1. Most urgently, update the .dt template to match the current Dlang.org
 style.

 2. Ideally, the .dt templates need to be removed, and DDox made to use the
 existing DDoc templates. This is so future website updates are immediately
 reflected in DDox, to avoid this situation in the future.


I'm leaning in the other direction: the website should not be based on a
macro processing system, but rather on a web framework. However, we use the
*content* on dlang.org to generate other targets than the website. It would
be unacceptable to kill these targets just to switch to another framework,
so there's a compromise to find here.
Relevant link: http://forum.dlang.org/thread/m9g1kt$1j01$1 digitalmars.com

Right now all the boilerplate of the website (navigation, basic layout)
lies within the 'DDOC' macros, in which every file gets inserted. On the
long run I plan to switch this to a Diet template, so ddox and the website
will share it and it will reduce the maintenance burden. The format of the
content itself will not change, it will still be in ".dd" files, and they
will get processed by the site on startup. We'll get the best of both
world, keeping the possibility to output any target out of the specs, but
writting website-specific part in a proper framework.

I've got a PoC working, which generate exactly the same layout as dlang.org
(give or take a few whitespaces), but is based on Vibe.d:
http://doc.mimiks.net:8000/changelog.html . Once it's polished, I'll P.R.
Feb 14 2015
parent reply "Vladimir Panteleev" <vladimir thecybershadow.net> writes:
On Saturday, 14 February 2015 at 23:06:20 UTC, Mathias Lang wrote:

 We'll get the best of both
 world, keeping the possibility to output any target out of the 
 specs, but
 writting website-specific part in a proper framework.


And the advantages of this are..?

Sorry, but I don't think this is going to fly.

You are proposing switching parts of the the website to Diet 
templates. This is one more DSL that contributors will need to 
know. We will have two different macro systems for building one 
website, and a ton of dependencies to boot.

Furthermore, this is probably the worst possible moment for such 
a proposal - you are suggesting that we move even more weight on 
something that is, right now, not merely unmaintained, but 
broken, and with no one wanting to fix it. Even if you complete 
your work, and assuming it gets accepted, who is going to 
maintain it?

Right now, it would take a very strong argument to prove that we 
need to migrate MORE parts to Vibe when the existing ones barely 
hold up.
Feb 14 2015
next sibling parent "Vladimir Panteleev" <vladimir thecybershadow.net> writes:
On Saturday, 14 February 2015 at 23:38:38 UTC, Vladimir Panteleev 
wrote:

 On Saturday, 14 February 2015 at 23:06:20 UTC, Mathias Lang 
 wrote:

 We'll get the best of both
 world, keeping the possibility to output any target out of the 
 specs, but
 writting website-specific part in a proper framework.


 And the advantages of this are..?


Another thing. I'm planning to make the forum and wiki use the 
Dlang.org theme - and not a copy, which will quickly become 
outdated, but actually use DDoc so that these websites will get 
updates automatically. This would be simple with DDoc, only a 
matter of splitting and refactoring a few macros here and there. 
How would this fit in your proposal?
Feb 14 2015
prev sibling parent Mathias Lang via Digitalmars-d <digitalmars-d puremagic.com> writes:
2015-02-15 0:38 GMT+01:00 Vladimir Panteleev via Digitalmars-d <
digitalmars-d puremagic.com>:


 On Saturday, 14 February 2015 at 23:06:20 UTC, Mathias Lang wrote:


 We'll get the best of both
 world, keeping the possibility to output any target out of the specs, but
 writting website-specific part in a proper framework.


 And the advantages of this are..?

 Sorry, but I don't think this is going to fly.

 You are proposing switching parts of the the website to Diet templates.
 This is one more DSL that contributors will need to know. We will have two
 different macro systems for building one website, and a ton of dependencies
 to boot.

 Furthermore, this is probably the worst possible moment for such a
 proposal - you are suggesting that we move even more weight on something
 that is, right now, not merely unmaintained, but broken, and with no one
 wanting to fix it. Even if you complete your work, and assuming it gets
 accepted, who is going to maintain it?

 Right now, it would take a very strong argument to prove that we need to
 migrate MORE parts to Vibe when the existing ones barely hold up.


One of the point of the vision document was to emphasize Vibe.d, and I'm
trying to do just that.
The advantages, from the top of my head, are:
- Dogfooding: we have a web framework, and we're using it for our website.
What message does it send ?
- Simplified build process: on the long run we'll be able to reduce, if not
ditch, the makefiles, and get the site up and running with a simple
command, no matter what platform you're on.
- Feedback on both Vibe.d and dub.
- More capabilities in the website: currently, anything dynamic has to be
done as a separate part (i.e. the forums), or in php (bugstats). In the
future such work could be integrated directly into the website. It could
also be made more dynamic, which opens a lot of possibilities, from simple
improvement (detecting the user's system and pushing the proper download
link to the top of the list), to more advanced one (providing Martin
Nowak's REPL, or better downloads / site consultation information).

A good point with this proposal is that it's not distruptive to the
existent: DDOC allows us to make this change smoothly, so if the change
gets pulled, it won't change anything to you, or anyone else that doesn't
want to use it. I expect some resistance, but I believe using it will be
the best way to prove it's usefulness.
Feb 15 2015
prev sibling parent =?UTF-8?B?U8O2bmtlIEx1ZHdpZw==?= <sludwig rejectedsoftware.com> writes:
Am 14.02.2015 um 10:46 schrieb Vladimir Panteleev:

 On Saturday, 14 February 2015 at 09:17:57 UTC, Andrei Alexandrescu wrote:

 Counting on your help!


 Here are some things that would help:

 1. Most urgently, update the .dt template to match the current Dlang.org
 style.


I've done that quickly (using a HTML to Jade converter). Will open a 
pull request soon.


 2. Ideally, the .dt templates need to be removed, and DDox made to use
 the existing DDoc templates. This is so future website updates are
 immediately reflected in DDox, to avoid this situation in the future.


This should be doable one way or another, it just probably requires some 
hacks, because Ddoc works top-down, while the Diet templates are 
processed bottom-up.


 3. Currently, DDox creates all .html files regardless if they've
 actually changed or not, thus making each generated file always have a
 new modification time. Because the website is uploaded via rsync, this
 greatly increases upload time. This can be solved by making DDox first
 create a Makefile include, or by simply making it not overwrite files
 with identical content.


I'll look into that.

https://github.com/rejectedsoftware/ddox/issues/73


 There is generally something very broken about the DDox templates. I've
 attempted to fix the website by adding a copy of the old style.css, and
 I've modified layout.dt like so:

 diff --git a/dpl-docs/views/layout.dt b/dpl-docs/views/layout.dt
 index c4ddcb0..2960625 100644
 --- a/dpl-docs/views/layout.dt
 +++ b/dpl-docs/views/layout.dt
    -19,7 +19,7    html(lang='en-US')



 -    link(rel='stylesheet', type='text/css',

 +    link(rel='stylesheet', type='text/css',


 type='text/javascript')



 Yet, no matter what I do, which files I delete or how I attempt to
 rebuild, the generated .html files still reference "style.css" and not
 "style-2014.css".


This is a known bug that I had completely forgotten about. It needs to 
get a priority boost.

https://github.com/D-Programming-Language/dub/issues/331


 I'm also getting strange linker errors when attempting to rebuild DDox:

 http://dump.thecybershadow.net/e6c93daabcbe9b01be9414d8d63913d8/0000009F.txt


 These only happen SOMETIMES. They don't happen on a clean build. I
 haven't identified the pattern, but it seems to vary between working and
 not working without me changing anything in the environment.


No idea what could cause this. Does running DUB with 
--build-mode=allAtOnce help (performs compile and link with a single DMD 
invocation)?
Feb 15 2015