Am 31.12.2013 11:05, schrieb Vladimir Panteleev:
P.S. How come your user agent (Thunderbird) is not emitting
format=flowed messages? According to [1], it supports format=flowed, and
can only be disabled via editing option strings.
[1]:
http://kb.mozillazine.org/Plain_text_e-mail_(Thunderbird)#Fl
XSLT is pretty useful for format conversion. It is also built
into most browsers, so you can just emit XML attach a XSLT
stylesheet and send it to a browser for transformation and
rendering.
Would be an advantage for anyone writing a book or article on D
(transform XML over to docbook, and fr
On Friday, January 03, 2014 12:12:44 Jacob Carlborg wrote:
> On 2014-01-03 01:56, Jonathan M Davis wrote:
> > That depends on how you go about post-processing. If you design your ddoc
> > macros with the idea that there's going to be post-processing, then they
> > can convert to other ddoc macros w
On 2014-01-02 22:38, H. S. Teoh wrote:
The limitation of macro systems is that, fundamentally speaking, no
semantics are assigned to macros. A macro is just an arbitrary name that
gets recursively substituted with some pre-specified pattern. The macro
engine doesn't know what any of the macros
On 2014-01-03 01:56, Jonathan M Davis wrote:
That depends on how you go about post-processing. If you design your ddoc
macros with the idea that there's going to be post-processing, then they can
convert to other ddoc macros which are designed for the post-processor to be
able to handle, and the
Am 02.01.2014 22:38, schrieb H. S. Teoh:
For example,
using `backticks` to write code snippets is definitely more readable
than writing $(D backticks), among many other things. But that does
introduce more syntax, which makes parsing more involved and also
requires learning more syntax. So, it's
On Thursday, January 02, 2014 13:38:22 H. S. Teoh wrote:
> But postprocessing also removes some of the advantage of ddoc: if you
> translate everything down to HTML tags, the postprocessor will have to
> reparse the HTML and resynthesize information on where sections
> begin/end, what constitutes a
On Wed, Jan 01, 2014 at 06:41:50PM -0800, Andrei Alexandrescu wrote:
> On 1/1/14 4:56 AM, Jacob Carlborg wrote:
[...]
> >I'm considering it to be a sort of tag, just with a different syntax.
> >Who said tags need to have an end tag. A less verbose a minimal
> >reliance on tags would be Markdown or
On 2014-01-01 21:38, Walter Bright wrote:
Ddoc doesn't generate HTML (the macros do), and the # means it's a local
reference, no file structure required.
Right, I failed to see that. But then that macro won't work for symbols
in other modules.
The file structure I was referring to was that
Am 01.01.2014 21:38, schrieb Walter Bright:
the # means it's a local reference, no file structure required.
A declaration being inside the *same* file is *also* part of the
file/directory structure. I could also be in different files. The point
is that if this kind of knowledge is encoded in
On 1/1/14 4:56 AM, Jacob Carlborg wrote:
On 2013-12-31 18:08, Andrei Alexandrescu wrote:
That's an exaggeration. The top of std.algorithm produces complex output
(two tables). The rest of the documentation is nice and legible.
std.algorithm contains 335 lines of ddoc comments. I would conside
On Wednesday, 1 January 2014 at 20:38:43 UTC, Walter Bright wrote:
Ddoc doesn't generate HTML (the macros do)
Ddoc doesn't generate HTML at all, not even with macros.
/// Returns true iff a > b
bool greaterThan(int a, int b);
Ddoc does /not/ do the right thing there. The best you can do is
w
On 1/1/2014 4:43 AM, Jacob Carlborg wrote:
On 2013-12-31 23:27, Walter Bright wrote:
I used this one in std.datetime:
LREF2=$(D $2)
That would require specific knowledge about how Ddoc generate the HTML and file
structure.
Ddoc doesn't generate HTML (the macros do), and the # mean
On Tue, Dec 31, 2013 at 06:12:02PM -0800, Andrei Alexandrescu wrote:
> On 12/31/13 11:51 AM, H. S. Teoh wrote:
> >On Tue, Dec 31, 2013 at 09:08:07AM -0800, Andrei Alexandrescu wrote:
> >>On 12/31/13 4:26 AM, Jacob Carlborg wrote:
> >[...]
> >4. It doesn't rely on embedded HTML, as such will imp
On 2013-12-31 22:08, Walter Bright wrote:
Not at all. The same ddoc sources are used to generate an ebook and a
Windows help file - which are based on html but require different html
to be generated, a difference handled by ddoc. The ebook and chm both
require post processing with tools supplied
On 2013-12-31 18:08, Andrei Alexandrescu wrote:
That's an exaggeration. The top of std.algorithm produces complex output
(two tables). The rest of the documentation is nice and legible.
std.algorithm contains 335 lines of ddoc comments. I would consider that
"hundreds", or does "hundreds" mea
On 2013-12-31 23:27, Walter Bright wrote:
I used this one in std.datetime:
LREF2=$(D $2)
That would require specific knowledge about how Ddoc generate the HTML
and file structure. Like replaces dots with an underscore in the module
name for the file name. std.datetime becomes std_d
Am 01.01.2014 02:21, schrieb Vladimir Panteleev:
On Tuesday, 31 December 2013 at 10:37:23 UTC, Sönke Ludwig wrote:
Am 31.12.2013 11:05, schrieb Vladimir Panteleev:
P.S. How come your user agent (Thunderbird) is not emitting
format=flowed messages? According to [1], it supports format=flowed, an
On 12/31/13 11:51 AM, H. S. Teoh wrote:
On Tue, Dec 31, 2013 at 09:08:07AM -0800, Andrei Alexandrescu wrote:
On 12/31/13 4:26 AM, Jacob Carlborg wrote:
[...]
4. It doesn't rely on embedded HTML, as such will impede extraction
and formatting for other purposes.
As far as I know this isn't ver
On Tuesday, 31 December 2013 at 10:37:23 UTC, Sönke Ludwig wrote:
Am 31.12.2013 11:05, schrieb Vladimir Panteleev:
P.S. How come your user agent (Thunderbird) is not emitting
format=flowed messages? According to [1], it supports
format=flowed, and
can only be disabled via editing option string
On 12/31/2013 1:17 PM, Jacob Carlborg wrote:
So which macro should I use to make cross referencing for arbitrary deep
hierarchies?
I used this one in std.datetime:
LREF2=$(D $2)
On 2013-12-31 21:52, Walter Bright wrote:
You don't need an efficient solution for ddoc files of readable size. It
only takes a few moments. I've spent far, far more time typing about it
here than it took to do. Some solutions are simply not worth the bother.
I've probably spent at least as mu
On 2013-12-31 19:16, Andrei Alexandrescu wrote:
Agreed. In all likelihood I misunderstood something because I thought
you were referring to cross-referencing text without any user intervention.
I made two suggestions, one which is completely automatic and one which
requires some syntax. It se
On 12/31/2013 4:14 AM, Jacob Carlborg wrote:
If Ddoc requires post processing to be useful it's a complete failure.
Not at all. The same ddoc sources are used to generate an ebook and a Windows
help file - which are based on html but require different html to be generated,
a difference handle
On 12/31/2013 4:37 AM, Jacob Carlborg wrote:
That doesn't sound very efficient.
You don't need an efficient solution for ddoc files of readable size. It only
takes a few moments. I've spent far, far more time typing about it here than it
took to do. Some solutions are simply not worth the bot
On Tue, Dec 31, 2013 at 09:08:07AM -0800, Andrei Alexandrescu wrote:
> On 12/31/13 4:26 AM, Jacob Carlborg wrote:
[...]
> >>>4. It doesn't rely on embedded HTML, as such will impede extraction
> >>>and formatting for other purposes.
> >
> >As far as I know this isn't very useful. For the other form
On 12/31/13 9:39 AM, Sönke Ludwig wrote:
Am 31.12.2013 17:48, schrieb Andrei Alexandrescu:
In a nutshell, "good cross-referencing is hard".
I don't think so at all (on the technical level). What is the issue with
using the #identifier.chain pattern for example? It seems simple enough
and I can
Am 31.12.2013 17:48, schrieb Andrei Alexandrescu:
On 12/31/13 1:28 AM, Sönke Ludwig wrote:
Am 31.12.2013 05:39, schrieb Andrei Alexandrescu:
On 12/30/13 1:00 PM, Walter Bright wrote:
On 12/30/2013 8:23 AM, Andrei Alexandrescu wrote:
Oh the default is to link and then disable manually? That's
On 12/31/13 4:26 AM, Jacob Carlborg wrote:
On 2013-12-31 01:05, Sönke Ludwig wrote:
Also, the official first four goals of DDOC are:
1. It looks good as embedded documentation, not just after it is
extracted and processed.
It certainly does not. Just have a look at the top of std.algori
On 12/31/13 1:28 AM, Sönke Ludwig wrote:
Am 31.12.2013 05:39, schrieb Andrei Alexandrescu:
On 12/30/13 1:00 PM, Walter Bright wrote:
On 12/30/2013 8:23 AM, Andrei Alexandrescu wrote:
Oh the default is to link and then disable manually? That's still
manual, just
the default is different :o). I
Am Tue, 31 Dec 2013 13:27:17 +0100
schrieb Jacob Carlborg :
> On 2013-12-31 10:31, Marco Leise wrote:
>
> > I am VERY much in favor of a more MarkDown style syntax and #
> > for identifier references! It is also very verbose to create
> > bullet-point lists and you always have to double-check you
On 2013-12-30 23:10, Walter Bright wrote:
The "query" part, meaning it highlighted each one and asked for yes/no.
http://www.gnu.org/software/emacs/manual/html_node/emacs/Query-Replace.html
That doesn't sound very efficient. Regardless of that, the current
macros still don't work. How do you
On 2013-12-31 11:05, Vladimir Panteleev wrote:
I agree that a good compromise would be to lighten the syntactic overhead.
How about using the $(D) macro instead of $(REF)? This macro
syntax-highlights its parameter as D code, and in Phobos it is already
used for identifiers, so I think a good s
On 2013-12-31 10:31, Marco Leise wrote:
I am VERY much in favor of a more MarkDown style syntax and #
for identifier references! It is also very verbose to create
bullet-point lists and you always have to double-check you
don't forget to replace all ) with $(RPAREN). If you misspell
anything it
On 2013-12-31 01:05, Sönke Ludwig wrote:
Also, the official first four goals of DDOC are:
1. It looks good as embedded documentation, not just after it is
extracted and processed.
It certainly does not. Just have a look at the top of std.algorithm or
std.uni. Hundreds of lines of Ddoc m
On 2013-12-31 00:37, Walter Bright wrote:
I don't see any particular advantage to using (name) rather than $(REF
name), and some serious disadvantages with false positives like
func(param). Oops! A markup language should really strive to minimize
special syntax. (I'm often tripped up by false po
On Tuesday, 31 December 2013 at 09:29:20 UTC, Sönke Ludwig wrote:
My favorite solution would be to introduce a simple
#identifier.chain or
@identifier.chain syntax to let the compiler or documentation
generator
insert the proper links or macro calls. Using a sepecial $(REF
identifier.chain) pse
Am Tue, 31 Dec 2013 10:28:46 +0100
schrieb Sönke Ludwig :
> Am 31.12.2013 05:39, schrieb Andrei Alexandrescu:
> > On 12/30/13 1:00 PM, Walter Bright wrote:
> >> On 12/30/2013 8:23 AM, Andrei Alexandrescu wrote:
> >>> Oh the default is to link and then disable manually? That's still
> >>> manual, j
Am Tue, 31 Dec 2013 00:13:41 +0100
schrieb Sönke Ludwig :
> [...] I very much agree with them, but the
> current reality looks like the opposite - lots of macro-pseudo-HTML
> markup, very difficult to read unprocessed in many places. So something
> like using "#" or "()" to mark symbols + automati
Am 31.12.2013 05:39, schrieb Andrei Alexandrescu:
> On 12/30/13 1:00 PM, Walter Bright wrote:
>> On 12/30/2013 8:23 AM, Andrei Alexandrescu wrote:
>>> Oh the default is to link and then disable manually? That's still
>>> manual, just
>>> the default is different :o). I can work with that.
>>
>> As
On 12/30/13 1:00 PM, Walter Bright wrote:
On 12/30/2013 8:23 AM, Andrei Alexandrescu wrote:
Oh the default is to link and then disable manually? That's still
manual, just
the default is different :o). I can work with that.
As I mentioned elsewhere, I dislike the requirement to use the inverse
Am 31.12.2013 00:37, schrieb Walter Bright:
> On 12/30/2013 3:13 PM, Sönke Ludwig wrote:
>> Am 30.12.2013 23:13, schrieb Walter Bright:
>>> On 12/30/2013 1:25 PM, Sönke Ludwig wrote:
Identifiers in documentation comments that are function parameters or
are names that are in scope at the a
On 12/30/2013 3:13 PM, Sönke Ludwig wrote:
Am 30.12.2013 23:13, schrieb Walter Bright:
On 12/30/2013 1:25 PM, Sönke Ludwig wrote:
Identifiers in documentation comments that are function parameters or
are names that are in scope at the associated declaration are emphasized
in the output.
So the
Am 30.12.2013 23:13, schrieb Walter Bright:
> On 12/30/2013 1:25 PM, Sönke Ludwig wrote:
>> Identifiers in documentation comments that are function parameters or
>> are names that are in scope at the associated declaration are emphasized
>> in the output.
>>
>> So the same problem is already realit
On 12/30/2013 1:25 PM, Sönke Ludwig wrote:
Identifiers in documentation comments that are function parameters or
are names that are in scope at the associated declaration are emphasized
in the output.
So the same problem is already reality - you already have to go through
the documentation to se
On 12/30/2013 1:31 PM, Jacob Carlborg wrote:
On 2013-12-30 21:58, Walter Bright wrote:
I'll have to disagree on that. I just finished doing it with
std.datetime, and it didn't take more than a few minutes with global
query-search-replace.
How did you limit that search to only the documentation
On 2013-12-30 21:58, Walter Bright wrote:
I've run into this a few times, and it cannot be dismissed easily.
Worse, there is the issue of how one overrides the auto-link generation
to be the right link.
I guess that would require a macro.
I'll have to disagree on that. I just finished doing
Am 30.12.2013 22:00, schrieb Walter Bright:
> On 12/30/2013 8:23 AM, Andrei Alexandrescu wrote:
>> Oh the default is to link and then disable manually? That's still
>> manual, just
>> the default is different :o). I can work with that.
>
> As I mentioned elsewhere, I dislike the requirement to use
On 12/30/2013 12:33 PM, Sönke Ludwig wrote:
> [...]
I've pretty much replied to these points in my response to Jacob and Andrei.
Am 30.12.2013 21:58, schrieb Walter Bright:
>>> 2. Using the word S as a word, not in reference to symbol S, would
>>> generate a hyperlink which would not make sense.
>>
>> I've have seen that happened a couple of times with documentation
>> generators
>> that support it, it has never bother me. A
On 12/30/2013 8:23 AM, Andrei Alexandrescu wrote:
Oh the default is to link and then disable manually? That's still manual, just
the default is different :o). I can work with that.
As I mentioned elsewhere, I dislike the requirement to use the inverse feature.
Consider maintenance - I add a sy
On 12/30/2013 12:14 PM, Jacob Carlborg wrote:
On 2013-12-30 20:08, Walter Bright wrote:
This will create many unwanted links, in three scenarios:
I don't think so, see below.
1. In the description for S, there should not be hyperlinks to S. These
would be annoying - when you click on them,
Am I slow... ;)
Am 30.12.2013 20:08, schrieb Walter Bright:
> On 12/29/2013 9:38 AM, Jacob Carlborg wrote:
>> A. Automatic cross reference
>>
>> Automatically create links for all matching symbols in the current
>> scope. That
>> means to create a link to a symbol in the current scope it's enough to
>> mention
>>
On 2013-12-30 20:08, Walter Bright wrote:
This will create many unwanted links, in three scenarios:
I don't think so, see below.
1. In the description for S, there should not be hyperlinks to S. These
would be annoying - when you click on them, nothing will happen.
The compiler knows which
On 12/29/2013 9:38 AM, Jacob Carlborg wrote:
A. Automatic cross reference
Automatically create links for all matching symbols in the current scope. That
means to create a link to a symbol in the current scope it's enough to mention
it's name in the documentation.
This will create many unwanted
Am 30.12.2013 17:31, schrieb Andrei Alexandrescu:
> On 12/29/13 10:35 AM, Sönke Ludwig wrote:
>> Am 29.12.2013 18:38, schrieb Jacob Carlborg:
>>> A. Automatic cross reference
>>
>> This is done for the DDOX based docs that were supposed to end up on the
>> home page at some point:
>
> It's past ti
On 12/29/13 10:35 AM, Sönke Ludwig wrote:
Am 29.12.2013 18:38, schrieb Jacob Carlborg:
A. Automatic cross reference
This is done for the DDOX based docs that were supposed to end up on the
home page at some point:
It's past time we do this. So the code is in there, we need to build it
appro
On 12/30/13 8:10 AM, Sönke Ludwig wrote:
In my experience it is far more annoying to have the source files
littered with $(MACROS) instead of putting a few _underscores to avoid
bogus links (not to mention that most of the time this results in no
links at all due to laziness).
Oh the default is
On 12/30/13 4:55 AM, Sönke Ludwig wrote:
Am 30.12.2013 13:47, schrieb Jacob Carlborg:
On 2013-12-30 12:39, Sönke Ludwig wrote:
Although I think that it is more important to have a well defined
documentation format that can be processed by external tools, it would
indeed be much nicer if for ex
Am 30.12.2013 16:57, schrieb Andrei Alexandrescu:
> On 12/30/13 3:39 AM, Sönke Ludwig wrote:
>> Am 30.12.2013 11:24, schrieb Jacob Carlborg:
>>> On 2013-12-29 19:35, Sönke Ludwig wrote:
>>>
This is done for the DDOX based docs that were supposed to end up on
the
home page at some poi
On 12/30/13 3:39 AM, Sönke Ludwig wrote:
Am 30.12.2013 11:24, schrieb Jacob Carlborg:
On 2013-12-29 19:35, Sönke Ludwig wrote:
This is done for the DDOX based docs that were supposed to end up on the
home page at some point:
BTW, although DDOX seems to be the best solution currently. It stil
Am 30.12.2013 13:47, schrieb Jacob Carlborg:
> On 2013-12-30 12:39, Sönke Ludwig wrote:
>
>> Although I think that it is more important to have a well defined
>> documentation format that can be processed by external tools, it would
>> indeed be much nicer if for example DMD could automatically em
On 2013-12-30 11:26, Jakob Ovrum wrote:
Yep, its only benefit is that it's a standardized set of macros and
works for any reasonably deep hierarchy.
Not as far as I can see. What I can see it only supports one level of
packages. That means basically a flat hierarchy like Phobos. All of my
pr
On 2013-12-30 12:39, Sönke Ludwig wrote:
Although I think that it is more important to have a well defined
documentation format that can be processed by external tools, it would
indeed be much nicer if for example DMD could automatically emit $(XREF
...) or similar for recognized symbol names. A
Am 30.12.2013 11:24, schrieb Jacob Carlborg:
> On 2013-12-29 19:35, Sönke Ludwig wrote:
>
>> This is done for the DDOX based docs that were supposed to end up on the
>> home page at some point:
>
> BTW, although DDOX seems to be the best solution currently. It still
> feels like a workaround for
On Monday, 30 December 2013 at 10:23:25 UTC, Jacob Carlborg wrote:
Based on the documentation it looks like it has the same
problems as the current approach, that is:
Yep, its only benefit is that it's a standardized set of macros
and works for any reasonably deep hierarchy.
bootDoc is about
On 2013-12-30 10:43, Jakob Ovrum wrote:
bootDoc[1] fixes this (thanks to Denis) with a number of standard macros
that are reasonably easy to use[2].
Based on the documentation it looks like it has the same problems as the
current approach, that is:
* Multiple macros are needed for something
On 2013-12-29 19:35, Sönke Ludwig wrote:
This is done for the DDOX based docs that were supposed to end up on the
home page at some point:
BTW, although DDOX seems to be the best solution currently. It still
feels like a workaround for something that should be fixed in the compiler.
--
/Jac
30-Dec-2013 14:19, Jacob Carlborg пишет:
On 2013-12-30 05:05, H. S. Teoh wrote:
Not only so, even without cross-referencing, the way Ddoc currently does
referencing *within* a module is faulty, because it does not take
symbols declared in nested scopes into account. For example:
module mym
On 2013-12-30 05:05, H. S. Teoh wrote:
Not only so, even without cross-referencing, the way Ddoc currently does
referencing *within* a module is faulty, because it does not take
symbols declared in nested scopes into account. For example:
module mymodule;
/// docs here
On Sunday, 29 December 2013 at 17:38:55 UTC, Jacob Carlborg wrote:
If nothing has happened recently the current situation of cross
referencing in Ddoc sucks. What's currently being used in the
Phobos documentation is the XREF, CXREF and ECXREF ddoc macros.
These macros take two argu
On Sun, Dec 29, 2013 at 06:38:55PM +0100, Jacob Carlborg wrote:
> If nothing has happened recently the current situation of cross
> referencing in Ddoc sucks. What's currently being used in the Phobos
> documentation is the XREF, CXREF and ECXREF ddoc macros. These
> macros t
On 2013-12-29 19:35, Sönke Ludwig wrote:
This is done for the DDOX based docs that were supposed to end up on the
home page at some point:
http://forum.dlang.org/thread/l9poef$210u$1...@digitalmars.com
http://vibed.org/temp/dlang.org/library/index.html
Right, forgot about that. When _are_ DDO
Am 29.12.2013 18:38, schrieb Jacob Carlborg:
> A. Automatic cross reference
This is done for the DDOX based docs that were supposed to end up on the
home page at some point:
http://forum.dlang.org/thread/l9poef$210u$1...@digitalmars.com
http://vibed.org/temp/dlang.org/library/index.html
> * It m
If nothing has happened recently the current situation of cross
referencing in Ddoc sucks. What's currently being used in the Phobos
documentation is the XREF, CXREF and ECXREF ddoc macros. These macros
take two arguments, append "std", "core" or "etc" and
76 matches
Mail list logo
